[codex] Add resource membership controls (#6677)

## Thinking Path

> - Paperclip orchestrates AI-agent companies through company-scoped
issues, projects, agents, and board-visible workflows.
> - The board sidebar and project list are the daily navigation surface
for that control plane.
> - Users need to keep all projects and agents accessible while hiding
resources they have intentionally left from their own sidebar.
> - That requires user-scoped resource membership state backed by
company-scoped API and database contracts.
> - The branch also needed to preserve HTTP worktree login sessions and
keep the project list easier to scan after membership grouping.
> - This pull request adds resource membership controls, sidebar leave
actions, grouped/sortable project listings, and focused tests.
> - The benefit is a cleaner personal workspace view without weakening
company-scoped access to the underlying project or agent detail pages.

## What Changed

- Added `project_memberships` and `agent_memberships` tables with
API/shared/server contracts for current-user join/leave state.
- Renumbered the membership migration to `0090_resource_memberships`
after rebasing onto current `master`, and made it idempotent for anyone
who had applied the old branch-local `0087` migration.
- Added project and agent sidebar leave actions, plus list filtering
that waits for membership state before hiding resources.
- Added grouped project listing, project sorting controls, and reserved
row subtitle height for cleaner scanning.
- Fixed HTTP auth cookie security handling so HTTP worktree sessions can
persist.
- Updated focused server and UI tests for the new membership, sidebar,
project list, and auth behavior.

## Verification

- `pnpm exec vitest run server/src/__tests__/better-auth.test.ts
server/src/__tests__/resource-memberships-routes.test.ts
ui/src/pages/Projects.test.tsx
ui/src/components/SidebarProjects.test.tsx
ui/src/components/SidebarAgents.test.tsx
ui/src/components/MembershipAction.test.tsx
ui/src/components/EntityRow.test.tsx`
- Confirmed the branch is rebased on current `origin/master`.
- Confirmed the PR diff does not include `pnpm-lock.yaml` or
`.github/workflows` changes.

## Risks

- Migration safety: low to medium. The migration now uses `IF NOT
EXISTS` / guarded constraints and is numbered after current master
migrations, but it should still get CI coverage against fresh databases.
- UI behavior: low. Left resources are hidden from sidebar only after
membership state loads; direct detail access remains available.
- Auth behavior: low. Cookie security is relaxed only for HTTP/private
local-style origins where secure cookies would prevent login
persistence.

> 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

- OpenAI GPT-5 Codex coding agent, tool-enabled shell/git workflow,
context window not exposed by runtime.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

Screenshot note: no browser screenshots were captured in this heartbeat;
the UI changes are covered by focused component tests above.

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

.agents/skills/release-changelog-discord-message/SKILL.md

@@ -0,0 +1,406 @@
+---
+name: release-changelog-discord-message
+description: >
+  Write the Discord release announcement for a stable Paperclip release. Companion
+  to `release-changelog` — that skill produces the file at `releases/vYYYY.MDD.P.md`;
+  this one turns that file into a single copy-pasteable Discord post in dotta's
+  voice and attaches it as the `discord_announcement` document on the release
+  issue.
+---
+
+# Release Discord Announcement Skill
+
+Write the Discord release announcement for the **stable** Paperclip release.
+
+This is the companion to `.agents/skills/release-changelog/SKILL.md`. That skill
+generates the file at `releases/vYYYY.MDD.P.md`. This skill turns that file into
+a single copy-pasteable Discord block, in dotta's voice, and posts it as the
+`discord_announcement` document on the release issue.
+
+## What dotta said
+
+> This is for discord — try to follow my format. If I have a section where I
+> think about the future, pull from recent issues we're working on etc.
+
+The Discord announcement is **not** the changelog. The changelog is exhaustive;
+the announcement is opinionated, in-voice, and built around the same handful of
+shipped highlights plus a real "what's next" + "what's on my mind" pulled from
+current Paperclip work — not invented.
+
+## When to use
+
+- After `release-changelog` has produced `releases/vYYYY.MDD.P.md` on the
+  release worktree/PR.
+- When the release issue (the one assigned by the release routine) asks for a
+  Discord announcement, or has a `discord_announcement` document that needs to
+  be refreshed for a new date/version.
+- Never run this in isolation. The version, date, contributor list, and
+  highlight set MUST match the matching changelog file — if the changelog has
+  been updated, refresh this too.
+
+## Output
+
+A single fenced markdown code block, ready to paste into Discord. Attached as
+issue document key `discord_announcement` on the release issue, and pasted
+verbatim into a comment on that issue so the human can copy it out.
+
+```bash
+PUT /api/issues/{releaseIssueId}/documents/discord_announcement
+{
+  "title": "Discord announcement",
+  "format": "markdown",
+  "body": "<the announcement>",
+  "baseRevisionId": "<latest if updating>"
+}
+```
+
+If the document already exists, fetch it first and pass the current
+`baseRevisionId`. Never overwrite silently — if the version has changed since
+the document was last written, mention what changed in the issue comment.
+
+## Format (follow this template)
+
+Use Discord emoji shortcodes (`:paperclip:`, `:lock:`, `:brain:` …) — NOT the
+Unicode emoji. Discord renders the shortcodes; the changelog file uses prose.
+
+```
+:paperclip: :paperclip: :paperclip: CLIPPERS!!! v{VERSION} IS OUT :paperclip: :paperclip: :paperclip:
+
+OFFICIAL TWITTER: https://x.com/papercliping - follow it, report any others
+
+## Highlights
+
+:emoji: **Feature Name** - one-sentence description in dotta's voice.
+:emoji: **Feature Name** - …
+:emoji: **Feature Name** - …
+
+... and a long tail of {flavor of the rest}. Read the [full release notes](<github link>).
+
+## WHATS NEXT (:motorway:  Roadmap)
+
+* **Theme A** - one-line forward-looking blurb
+* **Theme B** - …
+* **Theme C** - …
+
+## What's on my mind
+
+* **Topic** - what's bugging dotta / what's queued / open questions
+* **Topic** - …
+
+## PRESS                              (optional — only if there is real press)
+
+* **Outlet / Person** - what happened ([link](<x.com link>))
+
+## WHAT I NEED FROM YOU               (optional — only if there's a real ask)
+
+FOLLOW THE TWITTER: https://x.com/papercliping - that's the only official one
+TELL ME if you're using Paperclip in your business - I want to meet you
+
+## Community
+
+Thank you to everyone who contributed to this release!
+
+```
+@username1, @username2, @username3
+```
+
+## In Summary
+
+PAPERCLIP IS THE AI ORCHESTRATOR FOR HUMANS TO ACCOMPLISH 100x MORE WORK
+
+Every single person will be managing a team of a dozen, or a hundred, or a
+thousand agents and Paperclip will be the default tool to manage it all.
+
+ITS TIME TO CLIP :paperclip: :paperclip: :paperclip:
+
+FULL RELEASE NOTES
+
+https://github.com/paperclipai/paperclip/blob/master/releases/v{VERSION}.md
+
+||@everyone||
+```
+
+Notes on the template:
+
+- The opening and closing `:paperclip: :paperclip: :paperclip:` bookends are
+  part of the brand — keep them.
+- Sections may be UPPERCASE or Title Case — dotta has used both. Pick a style
+  and stay consistent within a single post.
+- Use `||@everyone||` (Discord spoiler-wrapped) at the very end so it pings
+  exactly once when the spoiler is removed by the poster.
+
+## Language tips
+
+These are extracted from how dotta has written the last several announcements.
+Mimic this register; do not invent a "professional" tone.
+
+- **First person, conversational.** "I want to meet companies using Paperclip",
+  "what's on my mind", "if that's you let me know". Not "Paperclip is excited
+  to announce".
+- **ALL CAPS for excitement and asks**, especially in the opener, the section
+  headers, the "WHAT I NEED FROM YOU" section, and the closing tagline. Do not
+  ALL-CAPS feature descriptions.
+- **One emoji shortcode per highlight bullet**, picked to evoke the feature
+  (`:lock:` for secrets, `:brain:` for planning, `:mag:` for search,
+  `:cloud:` for cloud / sandbox, `:jigsaw:` for plugins, `:rewind:` for
+  history/restore, `:thread:` for threads, etc.).
+- **Highlight bullets are one sentence**, opinionated, told from the user's
+  perspective — "the cloud-secrets prereq is real now", not "added support
+  for…".
+- **Tail line after highlights** wraps the rest in a single sentence and links
+  to the full release notes ("… and a long tail of {flavor}. Read the [full
+  release notes](url).").
+- **"WHATS NEXT" is forward-looking themes**, not a literal sprint list. 3–5
+  bullets is the right size. Pull these from active goals, in-flight projects,
+  and recent issues the team is working on — do not invent themes.
+- **"What's on my mind"** is dotta's personal/strategic thinking — docs gaps,
+  philosophical positioning ("we're the human control plane for ai labor"),
+  invitations ("if you've ever wanted to write about how you use Paperclip,
+  hit me up"). Pull real tensions from recent issues/comments; do not invent.
+- **Press section** is optional. Only include it if there is real press in the
+  release window (a tweet, a podcast, a talk, a star milestone). No press →
+  drop the section entirely.
+- **"WHAT I NEED FROM YOU"** is optional. Use it for a single concrete ask
+  (follow the twitter, intros, beta sign-ups). No real ask → drop it.
+- **Community** is the same contributors list that's in the changelog file,
+  fenced in a triple-backtick block, comma-separated `@username, @username`.
+  Exclude bots and Paperclip founders, same rules as the changelog skill.
+- **The "In Summary" mission line** evolves slowly. Use the most recent
+  variant unless dotta tells you otherwise. Recent variants:
+  - "PAPERCLIP IS THE AI ORCHESTRATOR FOR HUMANS TO ACCOMPLISH 100x MORE WORK"
+  - "PAPERCLIP WILL BE THE DEFAULT AGENT-MANAGEMENT TOOL FOR EVERY COMPANY"
+  - "Paperclip will be _the_ control plane for AI agents in **every** company."
+- **Closing tagline** is always `ITS TIME TO CLIP :paperclip: :paperclip:
+  :paperclip:`. Keep it.
+
+## Workflow
+
+1. Read the matching `releases/vYYYY.MDD.P.md` produced by `release-changelog`.
+   Use the version and contributor list from that file — never re-derive them.
+2. Read the **release issue thread** (the one assigned to you that ran the
+   release routine) — comments + linked issues + recent issues in the company
+   are the source for `WHATS NEXT` and `What's on my mind`. Pull real themes,
+   not invented ones.
+3. Re-read the three verbatim examples below — they're the canonical voice.
+4. Draft the announcement using the template above.
+5. PUT it as the `discord_announcement` document on the release issue (see
+   "Output" above). If updating, send the latest `baseRevisionId`.
+6. Post a comment on the release issue that includes the announcement inside a
+   single fenced markdown code block, so dotta can copy-paste it into Discord
+   without opening the document.
+
+Do not publish to Discord. This skill only prepares the artifact.
+
+## Verbatim previous examples
+
+Three previous Discord announcements from dotta, included **verbatim** as the
+ground-truth examples for voice, structure, and emoji usage. When in doubt,
+match these.
+
+### Example 1 — v2026.403.0
+
+```
+CLIPPERS! v2026.403.0 has dropped!! :paperclip: :paperclip: :paperclip:
+
+## Highlights
+
+:inbox_tray:  **Inbox overhaul** - there is a new "mine" tab that has mail-client like keyboard shortcuts. It's my new default view for managing work
+:thumbsup:  **Feedback and evals** - you can now vote :thumbsup: / :thumbsdown: on your agent's responses. If you choose to share your traces with me, I'll use it to make Paperclip better. In either case you can export locally for your own org's learning
+:page_with_curl:  **Document revisions** - you can now restore old versions of your documents
+:ping_pong:  **Telemetry** - this version has anonymized telemetry that helps me better understand the basic uses of Paperclip (adapters and so on) - if you hate that, just it disable with `DO_NOT_TRACK=1` or `PAPERCLIP_TELEMETRY_DISABLED=1` environment variables
+:construction_worker: **Execution Workspaces (experimental)** - Paperclip is not a "code review" tool, but I have been finding worktrees are important for certain projects. Enable it in experimental settings
+:loop:  **Routine variables** - sometimes you need to customize a routine and the new variables feature makes that easy
+
+PLUS **tons** of improvements aound adapters, bugfixes, qol
+
+## COMMUNITY
+
+HUGE THANKS to the contributors with commits in this release:
+
+```
+@aronprins, @bittoby, @edimuj, @HenkDz, @kevmok, @mvanhorn, @radiusred, @remdev, @statxc, @vanductai
+```
+
+## WHATS NEXT (ROADMAP)
+
+* **Multi-human users** -- you've been asking for it, we have a draft and will have this shortly
+* **Sandbox execution** - the other half of cloud deployment: run your agents in a sandbox across any provider
+
+PLUS: just dealing with the excellent PRs we have sitting in our inbox.
+
+**What's also on my mind (coming soonish)**
+
+* MAXIMIZER MODE - for when you've got a dream and tokens to burn
+* Artifacts, work products, and deployments
+* CEO Chat
+* Stronger agent defaults
+
+## PRESS
+
+I've been doing my part to spread the word about Paperclip
+
+* We talked to the incredible [Andrew Warner of Mixergy Fame](https://x.com/dotta/status/2039087507514507407)
+* We gave a tutorial with the [inimitable Greg Isenberg](https://x.com/dotta/status/2037279902445994345)
+* We met with the [Seed Club guys](https://x.com/dotta/status/2039020365926576377)
+* We crossed [40k stars (46k now!)](https://x.com/dotta/status/2038638188227387613)
+* ... and a couple others that will be released in a few days
+
+## SUCCESS STORIES
+
+* [Nevo made $76k in march](https://x.com/dotta/status/2039406772859920758) after using Paperclip to automate his marketing
+* [Lewis Jackson](https://x.com/WhatSayLew/status/2039810227394978158) said 34 agents were already operating his trading firm through Paperclip and called it his "holy s***" AI moment.
+* [Neal Kotak](https://x.com/nkotak1/status/2039582439459209638) said Paperclip already runs most of Roominary for him and praised how strong the product is.
+* [Sam Woods](https://x.com/samwoods/status/2039039305960587755) said he knows several people who moved from OpenClaw to Paperclip, often with Hermes in the stack, and that they love it.
+* [Josh Galt](https://x.com/JoshGalt/status/2039386307219095557) called Paperclip the coolest agent tooling he has used and said it is finally something that just works.
+
+## IN SUMMARY
+
+I know there are still some rough edges, but
+
+Paperclip will be *the* control plane for AI agents in **every** company.
+
+and I think we're moving at a pretty good clip :paperclip: :paperclip: :paperclip:
+
+FULL RELEASE NOTES HERE
+
+https://github.com/paperclipai/paperclip/releases/tag/v2026.403.0
+
+||@everyone||
+```
+
+### Example 2 — v2026.416.0
+
+```
+:paperclip: :paperclip: :paperclip: CLIPPERS!!! v2026.416.0 IS OUT :paperclip: :paperclip: :paperclip:
+
+## Highlights
+
+This release has *tons* of quality of life improvements around speed, performance, and workflow. You should notice that comment threads feel faster and your agents stay on task longer
+
+:thread: Issue chat threads now are a conversation more than comments
+:police_officer: Execution policies like **Reviewer** and **Approver** are now first-class in the harness (e.g. enforce that QA *must* review a task)
+:no_smoking: Blocker dependencies - first-class "wake on blocker resolved" which means now you can have "task graphs" that depend on one another and it's enforced by Paperclip
+:woman_feeding_baby: Parent-child tasks - better support for sub-tasks all around, which makes it much easier to organize your work
+
+And then a million fixes around ux, details, keyboard shortcuts, bug fixes, security fixes, etc. Really you should read the [full release notes here](https://github.com/paperclipai/paperclip/releases/tag/v2026.416.0)
+
+## COMMUNITY
+
+INCREDIBLE INCREDIBLE WORK BY folks with commits and reports in this release:
+
+```
+@AllenHyang, @antonio-mello-ai, @aronprins, @chrisschwer, @cleanunicorn, @DanielSousa, @davison, @ergonaworks, @HearthCore, @HenkDz, @KhairulA, @kimnamu, @Lempkey, @marysomething99-prog, @mvanhorn, @officialasishkumar, @plind-dm, @shoaib050326, @sparkeros, @wbelt, @offset, @sagilayani, @mattdonnelly10, @peaktwilight, @YuvalElbar6
+```
+
+## WHATS NEXT (:motorway:  Roadmap)
+
+* **Multi-human users** - in the last stages of testing, Paperclip is better with teams
+* **Memory Infrastructure** - your agents will remember everything about yoru business
+* **Sandbox execution** - run your agents anywhere
+
+## What's on my mind
+
+* I want to meet with companies who are using Paperclip in their business - if that's you let me know
+* We need more Paperclip tutorials, defaults, and education - thanks to @aronprins for his work in this area already!
+* We still need to get better at reviewing your PRs and we're improving our process every day
+* "Zero-human company" language has to go - we're the human control plane for ai labor
+* We're adding better support for *knowledge (wikis & files)*, *artifacts*, and *work product* in Paperclip soon.
+
+## PRESS
+
+* **AI Engineer Europe Tutorial** - I gave a tutorial for AIE. If someone is looking for a basics ABC of Paperclip [you can send them this](https://x.com/dotta/status/2044575580264316931)
+* **AI Club Chicago** - JB gave a talk on Paperclip [at AI Tinkerers in Chicago](https://x.com/developwithJB/status/2044281068778316268) !
+
+## IN SUMMARY
+
+PAPERCLIP WILL BE THE DEFAULT AGENT-MANAGEMENT TOOL FOR EVERY COMPANY
+
+If there's anything I can do to help you and your company use Paperclip, hit me up. Until then, enjoy the new release
+
+ITS TIME TO CLIP :paperclip: :paperclip: :paperclip:
+
+FULL RELEASE NOTES
+
+https://github.com/paperclipai/paperclip/releases/tag/v2026.416.0
+
+||@everyone||
+```
+
+### Example 3 — v2026.427.0
+
+```
+:paperclip: :paperclip: :paperclip: CLIPPERS!!! v2026.427.0 IS OUT :paperclip: :paperclip: :paperclip:
+
+THIS IS THE OFFICIAL TWITTER FOLLOW IT: https://x.com/papercliping
+
+## Highlights
+
+:man_feeding_baby: **MULTI USER** - you can now invite multiple users to your instance
+:factory_worker:  **HARDER WORKING** - robosut liveness continuations and lifecycle recovery means your instance tries harder before involving you
+:white_check_mark:  **SUBISSUE CHECKLISTS** - subissues have better ordering which allows for long-run planning
+:thread: **Rich Thread UX** - now your agents can ask you questions, ask for approvals, suggest tasks and you can approve or refine them right in your task threads
+:cloud:  **BETA: Sandbox Providers** - Cloud sandboxing is in beta - the API ships in this release and we'll be adding more providers
+... and *tons* of other improvements and bugfixes.
+
+## Community
+
+Thank you to everyone who contributed to this release!
+
+```
+@akhater, @aronprins, @GodsBoy, @LeonSGP43, @neerazz, @NoronhaH, @rbarinov, @rvanduiven, @SgtPooki, @superbiche
+```
+
+## WHATS NEXT (:motorway:  Roadmap)
+
+* **Longer-range planning and execution** - Paperclip will support longer and longer tasks and work until it's done
+* **Secrets Service v2** - an important prereq for Paperclip cloud
+* **Artifacts, memory, and knowledge**
+* **Conference Room** aka CEO/Agent Chat
+
+## What's on my mind
+
+* **Documentation & Blog posts** - I've fallen behind on the docs but aron has done a good job here - we'll be setting up Clips to help maintain these
+* **Paperclip Cloud** - will be a critical unlock for us, but even the shared team story needs developed more - *where should the work be done* and *where are the outputs stored* and *how do we surface them to users*? Each of these questions are a core Paperclip service that needs developed
+* **Paperclip Bench** - In the vein of SWE-Bench I've started an internal benchmark for Paperclip - we have to be able to measure that our changes are improving the system and not regressing
+* **Paperclip Connections Store** - connecting to Github, Slack, Google Docs, and the hundreds of other services we use every day should be easy, secure, and configurable per agent and team
+
+## Press
+
+I met with the [Wisemen about Paperclip](https://x.com/dotta/status/2045146539534827998)
+
+## WHAT I NEED FROM YOU
+
+FOLLOW THIS TWITTER ACCOUNT: https://x.com/papercliping - that's the only official one, report any others
+
+## In Summary
+
+PAPERCLIP IS THE AI ORCHESTRATOR FOR HUMANS TO ACCOMPLISH 100x MORE WORK
+
+Every single person will be managing a team of a dozen, or a hundred, or a thousand agents and Paperclip will be the default tool to manage it all.
+
+ITS TIME TO CLIP :paperclip: :paperclip: :paperclip:
+
+FULL RELEASE NOTES
+
+https://github.com/paperclipai/paperclip/blob/master/releases/v2026.427.0.md
+
+||@everyone||
+```
+
+## Review checklist
+
+Before handing off:
+
+1. Version + date match the matching `releases/vYYYY.MDD.P.md` exactly.
+2. Contributor list matches the changelog (same exclusions: bots, founders).
+3. Highlights are a subset of the changelog Highlights — same shipped features,
+   not invented or pre-alpha work.
+4. `WHATS NEXT` and `What's on my mind` are pulled from real recent issues /
+   active goals — not invented themes.
+5. Section style (UPPERCASE vs Title Case) is internally consistent.
+6. Closing tagline is `ITS TIME TO CLIP :paperclip: :paperclip: :paperclip:`
+   and `||@everyone||` is the very last line.
+7. Document `discord_announcement` is updated on the release issue, and the
+   announcement is also posted in a comment inside a fenced code block.
+
+This skill never posts to Discord. It only prepares the announcement artifact.

.github/workflows/pr.yml

@@ -62,7 +62,8 @@ jobs:
             pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
           fi
 
-  verify:
+  typecheck_release_registry:
+    name: Typecheck + Release Registry
     needs: [policy]
     runs-on: ubuntu-latest
     timeout-minutes: 20
@@ -88,12 +89,89 @@ jobs:
       - name: Typecheck workspaces whose build scripts skip TypeScript
         run: pnpm run typecheck:build-gaps
 
-      - name: Run general test suites
-        run: pnpm test:run:general
-
       - name: Verify release registry test coverage
         run: pnpm run test:release-registry
 
+  general_tests:
+    name: General tests (${{ matrix.group_label }})
+    needs: [policy]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - group: general-server
+            group_label: server
+          - group: general-workspaces-a
+            group_label: workspaces-a
+          - group: general-workspaces-b
+            group_label: workspaces-b
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run grouped general test suites
+        run: pnpm test:run:general -- --group '${{ matrix.group }}'
+
+  verify:
+    # Preserve the legacy required-check name while the underlying work runs in parallel.
+    name: verify
+    if: ${{ always() }}
+    needs: [typecheck_release_registry, general_tests, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Fail if any split verify lane failed
+        env:
+          TYPECHECK_RELEASE_REGISTRY_RESULT: ${{ needs.typecheck_release_registry.result }}
+          GENERAL_TESTS_RESULT: ${{ needs.general_tests.result }}
+          BUILD_RESULT: ${{ needs.build.result }}
+        run: |
+          test "$TYPECHECK_RELEASE_REGISTRY_RESULT" = "success"
+          test "$GENERAL_TESTS_RESULT" = "success"
+          test "$BUILD_RESULT" = "success"
+
+  build:
+    name: Build
+    needs: [policy]
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
       - name: Build
         run: pnpm build
 

.gitignore

@@ -55,4 +55,6 @@ tests/e2e/playwright-report/
 tests/release-smoke/test-results/
 tests/release-smoke/playwright-report/
 .superset/
+.superpowers/
 .claude/worktrees/
+.herenow

Dockerfile

@@ -28,6 +28,7 @@ COPY packages/adapters/codex-local/package.json packages/adapters/codex-local/
 COPY packages/adapters/cursor-cloud/package.json packages/adapters/cursor-cloud/
 COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/
 COPY packages/adapters/gemini-local/package.json packages/adapters/gemini-local/
+COPY packages/adapters/grok-local/package.json packages/adapters/grok-local/
 COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/
 COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/
 COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/
@@ -35,7 +36,9 @@ COPY packages/plugins/sdk/package.json packages/plugins/sdk/
 COPY --parents packages/plugins/sandbox-providers/./*/package.json packages/plugins/sandbox-providers/
 COPY packages/plugins/paperclip-plugin-fake-sandbox/package.json packages/plugins/paperclip-plugin-fake-sandbox/
 COPY packages/plugins/plugin-llm-wiki/package.json packages/plugins/plugin-llm-wiki/
+COPY packages/plugins/plugin-workspace-diff/package.json packages/plugins/plugin-workspace-diff/
 COPY patches/ patches/
+COPY scripts/link-plugin-dev-sdk.mjs scripts/
 
 RUN pnpm install --frozen-lockfile
 

cli/README.md

@@ -226,6 +226,21 @@ By default, agents run on scheduled heartbeats and event-based triggers (task as
 
 <br/>
 
+## Paperclip Cloud Sync
+
+Cloud upstream sync is behind the `Cloud Sync` experimental setting. Enable it in Instance Settings before pushing.
+
+```bash
+paperclipai cloud connect https://your-stack.paperclip.app
+paperclipai cloud connect https://your-stack.paperclip.app --no-browser
+paperclipai cloud push --company <local-company-id> --dry-run
+paperclipai cloud push --company <local-company-id>
+```
+
+`cloud connect` authorizes the local instance against the target stack and stores the upstream token in the local instance secret store. The default path opens a browser for consent; `--no-browser` uses the device-code flow and prints the verification URL and user code.
+
+`cloud push --dry-run` exports the selected local company, sends a preview bundle to the connected Cloud stack, and exits with code `2` when conflicts need user resolution. A schema mismatch exits with code `3`. Running without `--dry-run` stages chunks idempotently, applies the run, and prints the final summary and recent progress events.
+
 ## Development
 
 ```bash

cli/package.json

@@ -43,6 +43,7 @@
     "@paperclipai/adapter-cursor-cloud": "workspace:*",
     "@paperclipai/adapter-cursor-local": "workspace:*",
     "@paperclipai/adapter-gemini-local": "workspace:*",
+    "@paperclipai/adapter-grok-local": "workspace:*",
     "@paperclipai/adapter-opencode-local": "workspace:*",
     "@paperclipai/adapter-pi-local": "workspace:*",
     "@paperclipai/adapter-openclaw-gateway": "workspace:*",

cli/src/__tests__/cloud.test.ts

@@ -0,0 +1,243 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { CompanyPortabilityExportResult } from "@paperclipai/shared";
+import {
+  assertDiscoveryCompatible,
+  buildBundleFromLocalCompany,
+  cloudCommandExitCodes,
+  connectCloud,
+  resolveDeviceCodeExpiresAt,
+} from "../commands/client/cloud.js";
+import {
+  LocalUpstreamPushCoordinator,
+  normalizedContentHash,
+  type LocalUpstreamExportBundle,
+} from "../commands/client/cloud-transfer.js";
+import { getCloudConnection } from "../commands/client/cloud-store.js";
+
+const originalEnv = { ...process.env };
+const originalFetch = globalThis.fetch;
+
+describe("cloud CLI helpers", () => {
+  let tempHome: string;
+
+  beforeEach(() => {
+    tempHome = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-cloud-cli-"));
+    process.env = { ...originalEnv, PAPERCLIP_HOME: tempHome };
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+    globalThis.fetch = originalFetch;
+    vi.restoreAllMocks();
+    fs.rmSync(tempHome, { recursive: true, force: true });
+  });
+
+  it("connects with the device-code flow and stores the resulting cloud connection", async () => {
+    globalThis.fetch = vi.fn(async (url, init) => {
+      const requestUrl = String(url);
+      if (requestUrl.endsWith("/.well-known/paperclip-upstream")) {
+        return jsonResponse(discovery());
+      }
+      if (requestUrl.endsWith("/api/upstream-sync/device-code")) {
+        expect(JSON.parse(String(init?.body))).toMatchObject({
+          stackId: "stack-1",
+          scopes: ["upstream_import:preview", "upstream_import:write", "upstream_import:read"],
+        });
+        return jsonResponse({
+          deviceCode: "device-1",
+          userCode: "ABCD-EFGH",
+          verificationUri: "https://cloud.example.test/api/upstream-sync/device-code/approve",
+          expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          intervalSeconds: 0,
+        });
+      }
+      if (requestUrl.endsWith("/api/upstream-sync/token")) {
+        return jsonResponse({
+          accessToken: "upt_test",
+          scopes: ["upstream_import:preview"],
+          token: {
+            id: "token-1",
+            companyStackId: "stack-1",
+            targetOrigin: "https://cloud.example.test",
+            sourceInstanceId: "paperclip-local-default",
+            sourceInstanceFingerprint: "sha256:test",
+            scopes: ["upstream_import:preview"],
+            expiresAt: new Date(Date.now() + 60_000).toISOString(),
+          },
+        });
+      }
+      return jsonResponse({ error: "not_found" }, 404);
+    }) as typeof fetch;
+
+    const connection = await connectCloud("https://cloud.example.test", { noBrowser: true, json: true });
+
+    expect(connection.accessToken).toBe("upt_test");
+    expect(getCloudConnection("https://cloud.example.test")?.token.id).toBe("token-1");
+  });
+
+  it("hard-blocks incompatible transfer schema versions with the stable schema exit code", () => {
+    expect(() => assertDiscoveryCompatible(discovery({ supportedSchemaMajor: 99 }))).toThrow(/schema mismatch/i);
+    expect(cloudCommandExitCodes.schemaMismatch).toBe(3);
+  });
+
+  it("falls back to a bounded device-code expiry when the cloud omits or malforms expiresAt", () => {
+    const now = Date.UTC(2026, 4, 22, 13, 0, 0);
+    const validExpiry = "2026-05-22T13:05:00.000Z";
+
+    expect(resolveDeviceCodeExpiresAt(validExpiry, now)).toBe(Date.parse(validExpiry));
+    expect(resolveDeviceCodeExpiresAt(undefined, now)).toBe(now + 15 * 60_000);
+    expect(resolveDeviceCodeExpiresAt("not-a-date", now)).toBe(now + 15 * 60_000);
+  });
+
+  it("builds deterministic chunks with validated payload hashes", async () => {
+    const bundle = await buildTestBundle();
+
+    expect(bundle.chunks).toHaveLength(2);
+    expect(bundle.chunks[0]?.sha256).toBe(normalizedContentHash(bundle.chunks[0]?.payload));
+    expect(bundle.manifest.chunks[0]?.manifestHash).toBe(bundle.manifest.manifestHash);
+    expect(bundle.manifest.idempotencyKey).toBe((await buildTestBundle()).manifest.idempotencyKey);
+  });
+
+  it("reuses the same manifest and chunk identity when an interrupted apply is retried", async () => {
+    const bundle = await buildTestBundle();
+    const calls: Array<{ path: string; body: unknown }> = [];
+    const coordinator = new LocalUpstreamPushCoordinator({
+      targetOrigin: "https://cloud.example.test",
+      paperclipCompanyId: "target-company-1",
+      fetch: async (url, init) => {
+        const parsed = new URL(String(url));
+        const body = init?.body ? JSON.parse(String(init.body)) as unknown : {};
+        calls.push({ path: parsed.pathname, body });
+        if (parsed.pathname.endsWith("/runs")) return jsonResponse({ run: { id: "run-1" } });
+        return jsonResponse({ run: { id: "run-1" }, summary: { create: 0, update: 0, adopt: 0, skip: 2, conflict: 0, staleMapping: 0 } });
+      },
+    });
+
+    await coordinator.apply(bundle);
+    await coordinator.apply(bundle);
+
+    const runBodies = calls.filter((call) => call.path.endsWith("/runs")).map((call) => call.body as { manifest: { idempotencyKey: string } });
+    const chunkBodies = calls.filter((call) => call.path.endsWith("/chunks")).map((call) => call.body as { chunkIndex: number; sha256: string });
+    expect(runBodies).toHaveLength(2);
+    expect(runBodies[0]?.manifest.idempotencyKey).toBe(runBodies[1]?.manifest.idempotencyKey);
+    expect(chunkBodies[0]).toEqual(chunkBodies[2]);
+    expect(chunkBodies[1]).toEqual(chunkBodies[3]);
+  });
+});
+
+async function buildTestBundle(): Promise<LocalUpstreamExportBundle> {
+  return buildBundleFromLocalCompany({
+    localCompanyId: "local-company-1",
+    connection: {
+      id: "conn-1",
+      remoteUrl: "https://cloud.example.test",
+      targetOrigin: "https://cloud.example.test",
+      targetHost: "cloud.example.test",
+      stackId: "stack-1",
+      targetCompanyId: "target-company-1",
+      accessToken: "upt_test",
+      token: {
+        id: "token-1",
+        companyStackId: "stack-1",
+        targetOrigin: "https://cloud.example.test",
+        sourceInstanceId: "paperclip-local-default",
+        sourceInstanceFingerprint: "sha256:test",
+        scopes: ["upstream_import:preview"],
+        expiresAt: new Date(Date.now() + 60_000).toISOString(),
+      },
+      privateKeyPem: "unused",
+      sourcePublicKey: "unused",
+      sourceInstanceId: "paperclip-local-default",
+      sourceInstanceFingerprint: "sha256:test",
+      scopes: ["upstream_import:preview"],
+      createdAt: "2026-05-18T00:00:00.000Z",
+      updatedAt: "2026-05-18T00:00:00.000Z",
+    },
+    discovery: discovery(),
+    localApi: {
+      post: async <T>() => portabilityExport() as T,
+    },
+    maxEntitiesPerChunk: 1,
+    mode: "apply",
+  });
+}
+
+function discovery(overrides: Partial<{ supportedSchemaMajor: number }> = {}) {
+  return {
+    schema: "paperclip-upstream-discovery-v1",
+    stack: {
+      id: "stack-1",
+      slug: "cloud-test",
+      displayName: "Cloud Test",
+      companyId: "target-company-1",
+      origin: "https://cloud.example.test",
+    },
+    auth: {
+      deviceCode: {
+        deviceCodeUrl: "https://cloud.example.test/api/upstream-sync/device-code",
+        verificationUrl: "https://cloud.example.test/api/upstream-sync/device-code/approve",
+        tokenUrl: "https://cloud.example.test/api/upstream-sync/token",
+      },
+      scopes: ["upstream_import:preview", "upstream_import:write", "upstream_import:read"],
+    },
+    transfer: {
+      supportedSchemaMajor: overrides.supportedSchemaMajor ?? 1,
+      featureFlags: ["cloud_sync"],
+    },
+  };
+}
+
+function portabilityExport(): CompanyPortabilityExportResult {
+  return {
+    rootPath: ".",
+    paperclipExtensionPath: ".paperclip.yaml",
+    manifest: {
+      schemaVersion: 1,
+      generatedAt: "2026-05-18T00:00:00.000Z",
+      source: {
+        companyId: "local-company-1",
+        companyName: "Local Company",
+      },
+      includes: {
+        company: true,
+        agents: true,
+        projects: true,
+        issues: true,
+        skills: true,
+      },
+      company: {
+        path: "company.json",
+        name: "Local Company",
+        description: null,
+        brandColor: null,
+        logoPath: null,
+        attachmentMaxBytes: null,
+        requireBoardApprovalForNewAgents: false,
+        feedbackDataSharingEnabled: false,
+        feedbackDataSharingConsentAt: null,
+        feedbackDataSharingConsentByUserId: null,
+        feedbackDataSharingTermsVersion: null,
+      },
+      sidebar: null,
+      agents: [],
+      skills: [],
+      projects: [],
+      issues: [],
+      envInputs: [],
+    },
+    files: {
+      "README.md": "Local Company",
+    },
+    warnings: [],
+  };
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}

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

@@ -2,6 +2,8 @@ import { describe, expect, it } from "vitest";
 import { resolveRuntimeBind, validateConfiguredBindMode } from "@paperclipai/shared";
 import { buildPresetServerConfig } from "../config/server-bind.js";
 
+const ORIGINAL_PATH = process.env.PATH;
+
 describe("network bind helpers", () => {
   it("rejects non-loopback bind modes in local_trusted", () => {
     expect(
@@ -50,13 +52,18 @@ describe("network bind helpers", () => {
 
   it("falls back to loopback when no tailscale address is available for tailnet presets", () => {
     delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+    process.env.PATH = "";
 
-    const preset = buildPresetServerConfig("tailnet", {
-      port: 3100,
-      allowedHostnames: [],
-      serveUi: true,
-    });
+    try {
+      const preset = buildPresetServerConfig("tailnet", {
+        port: 3100,
+        allowedHostnames: [],
+        serveUi: true,
+      });
 
-    expect(preset.server.host).toBe("127.0.0.1");
+      expect(preset.server.host).toBe("127.0.0.1");
+    } finally {
+      process.env.PATH = ORIGINAL_PATH;
+    }
   });
 });

cli/src/__tests__/onboard.test.ts

@@ -7,6 +7,7 @@ import type { PaperclipConfig } from "../config/schema.js";
 
 const ORIGINAL_ENV = { ...process.env };
 const ORIGINAL_CWD = process.cwd();
+const ORIGINAL_PATH = process.env.PATH;
 
 function createExistingConfigFixture() {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-onboard-"));
@@ -171,8 +172,13 @@ describe("onboard", () => {
   it("keeps tailnet quickstart on loopback until tailscale is available", async () => {
     const configPath = createFreshConfigPath();
     delete process.env.PAPERCLIP_TAILNET_BIND_HOST;
+    process.env.PATH = "";
 
-    await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" });
+    try {
+      await onboard({ config: configPath, yes: true, invokedByRun: true, bind: "tailnet" });
+    } finally {
+      process.env.PATH = ORIGINAL_PATH;
+    }
 
     const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as PaperclipConfig;
     expect(raw.server.deploymentMode).toBe("authenticated");

cli/src/__tests__/worktree.test.ts

@@ -512,6 +512,45 @@ describe("worktree helpers", () => {
     }
   });
 
+  it("preserves repo-managed worktree checkouts when --force re-runs from the source repo", async () => {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-force-preserve-"));
+    const repoRoot = path.join(tempRoot, "repo");
+    const originalCwd = process.cwd();
+
+    try {
+      fs.mkdirSync(repoRoot, { recursive: true });
+      const repoConfigDir = path.join(repoRoot, ".paperclip");
+      fs.mkdirSync(repoConfigDir, { recursive: true });
+      fs.writeFileSync(path.join(repoConfigDir, "config.json"), "stale", "utf8");
+      fs.writeFileSync(path.join(repoConfigDir, ".env"), "STALE=1", "utf8");
+
+      // Simulate the repo-managed worktrees subfolder that holds every
+      // worktree checkout (the directory PAPA-358 reported as nuked).
+      const worktreesDir = path.join(repoConfigDir, "worktrees");
+      const checkoutDir = path.join(worktreesDir, "PAP-100-feature");
+      fs.mkdirSync(checkoutDir, { recursive: true });
+      const sentinelPath = path.join(checkoutDir, "sentinel.txt");
+      fs.writeFileSync(sentinelPath, "do-not-delete", "utf8");
+
+      process.chdir(repoRoot);
+
+      await worktreeInitCommand({
+        seed: false,
+        force: true,
+        fromConfig: path.join(tempRoot, "missing", "config.json"),
+        home: path.join(tempRoot, ".paperclip-worktrees"),
+      });
+
+      expect(fs.existsSync(sentinelPath)).toBe(true);
+      expect(fs.readFileSync(sentinelPath, "utf8")).toBe("do-not-delete");
+      expect(fs.existsSync(path.join(repoConfigDir, "config.json"))).toBe(true);
+      expect(fs.readFileSync(path.join(repoConfigDir, "config.json"), "utf8")).not.toBe("stale");
+    } finally {
+      process.chdir(originalCwd);
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
   itEmbeddedPostgres(
     "seeds authenticated users into minimally cloned worktree instances",
     async () => {

cli/src/adapters/registry.ts

@@ -5,6 +5,7 @@ import { printCodexStreamEvent } from "@paperclipai/adapter-codex-local/cli";
 import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";
 import { printCursorCloudEvent } from "@paperclipai/adapter-cursor-cloud/cli";
 import { printGeminiStreamEvent } from "@paperclipai/adapter-gemini-local/cli";
+import { printGrokStreamEvent } from "@paperclipai/adapter-grok-local/cli";
 import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";
 import { printPiStreamEvent } from "@paperclipai/adapter-pi-local/cli";
 import { printOpenClawGatewayStreamEvent } from "@paperclipai/adapter-openclaw-gateway/cli";
@@ -51,6 +52,11 @@ const geminiLocalCLIAdapter: CLIAdapterModule = {
   formatStdoutEvent: printGeminiStreamEvent,
 };
 
+const grokLocalCLIAdapter: CLIAdapterModule = {
+  type: "grok_local",
+  formatStdoutEvent: printGrokStreamEvent,
+};
+
 const openclawGatewayCLIAdapter: CLIAdapterModule = {
   type: "openclaw_gateway",
   formatStdoutEvent: printOpenClawGatewayStreamEvent,
@@ -66,6 +72,7 @@ const adaptersByType = new Map<string, CLIAdapterModule>(
     cursorLocalCLIAdapter,
     cursorCloudCLIAdapter,
     geminiLocalCLIAdapter,
+    grokLocalCLIAdapter,
     openclawGatewayCLIAdapter,
     processCLIAdapter,
     httpCLIAdapter,

cli/src/commands/client/cloud-store.ts

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolvePaperclipInstanceRoot } from "../../config/home.js";
+
+export interface CloudConnectionTokenRecord {
+  id: string;
+  companyStackId: string;
+  targetOrigin: string;
+  sourceInstanceId: string;
+  sourceInstanceFingerprint: string;
+  scopes: string[];
+  expiresAt: string;
+  [key: string]: unknown;
+}
+
+export interface CloudConnection {
+  id: string;
+  remoteUrl: string;
+  targetOrigin: string;
+  targetHost: string;
+  stackId: string;
+  stackSlug?: string | null;
+  stackDisplayName?: string | null;
+  targetCompanyId: string;
+  accessToken: string;
+  token: CloudConnectionTokenRecord;
+  privateKeyPem: string;
+  sourcePublicKey: string;
+  sourceInstanceId: string;
+  sourceInstanceFingerprint: string;
+  scopes: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface CloudConnectionStore {
+  version: 1;
+  connections: Record<string, CloudConnection>;
+  currentConnectionId?: string;
+}
+
+function defaultStore(): CloudConnectionStore {
+  return {
+    version: 1,
+    connections: {},
+  };
+}
+
+export function resolveCloudConnectionStorePath(): string {
+  return path.resolve(resolvePaperclipInstanceRoot(), "secrets", "cloud-upstream-connections.json");
+}
+
+export function readCloudConnectionStore(storePath = resolveCloudConnectionStorePath()): CloudConnectionStore {
+  if (!fs.existsSync(storePath)) return defaultStore();
+  const raw = JSON.parse(fs.readFileSync(storePath, "utf8")) as Partial<CloudConnectionStore> | null;
+  const connections: Record<string, CloudConnection> = {};
+  if (raw?.connections && typeof raw.connections === "object") {
+    for (const [id, value] of Object.entries(raw.connections)) {
+      const normalized = normalizeConnection(value);
+      if (normalized) connections[id] = normalized;
+    }
+  }
+  const currentConnectionId =
+    typeof raw?.currentConnectionId === "string" && connections[raw.currentConnectionId]
+      ? raw.currentConnectionId
+      : Object.values(connections).sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0]?.id;
+  return {
+    version: 1,
+    connections,
+    currentConnectionId,
+  };
+}
+
+export function writeCloudConnectionStore(
+  store: CloudConnectionStore,
+  storePath = resolveCloudConnectionStorePath(),
+): void {
+  fs.mkdirSync(path.dirname(storePath), { recursive: true });
+  fs.writeFileSync(storePath, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+}
+
+export function upsertCloudConnection(
+  connection: CloudConnection,
+  storePath = resolveCloudConnectionStorePath(),
+): CloudConnection {
+  const store = readCloudConnectionStore(storePath);
+  const existing = store.connections[connection.id];
+  const now = new Date().toISOString();
+  const next = {
+    ...connection,
+    createdAt: existing?.createdAt ?? connection.createdAt ?? now,
+    updatedAt: now,
+  };
+  store.connections[next.id] = next;
+  store.currentConnectionId = next.id;
+  writeCloudConnectionStore(store, storePath);
+  return next;
+}
+
+export function getCloudConnection(
+  remoteUrlOrOrigin?: string,
+  storePath = resolveCloudConnectionStorePath(),
+): CloudConnection | null {
+  const store = readCloudConnectionStore(storePath);
+  if (remoteUrlOrOrigin?.trim()) {
+    const needle = normalizeRemoteLookup(remoteUrlOrOrigin);
+    return Object.values(store.connections).find((connection) =>
+      normalizeRemoteLookup(connection.remoteUrl) === needle ||
+      normalizeRemoteLookup(connection.targetOrigin) === needle
+    ) ?? null;
+  }
+  return store.currentConnectionId ? store.connections[store.currentConnectionId] ?? null : null;
+}
+
+function normalizeRemoteLookup(value: string): string {
+  try {
+    const url = new URL(value);
+    return url.origin.replace(/\/+$/u, "");
+  } catch {
+    return value.trim().replace(/\/+$/u, "");
+  }
+}
+
+function normalizeConnection(value: unknown): CloudConnection | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  const id = stringValue(record.id);
+  const remoteUrl = stringValue(record.remoteUrl);
+  const targetOrigin = stringValue(record.targetOrigin);
+  const targetHost = stringValue(record.targetHost);
+  const stackId = stringValue(record.stackId);
+  const targetCompanyId = stringValue(record.targetCompanyId);
+  const accessToken = stringValue(record.accessToken);
+  const token = typeof record.token === "object" && record.token !== null && !Array.isArray(record.token)
+    ? record.token as CloudConnectionTokenRecord
+    : null;
+  const privateKeyPem = stringValue(record.privateKeyPem);
+  const sourcePublicKey = stringValue(record.sourcePublicKey);
+  const sourceInstanceId = stringValue(record.sourceInstanceId);
+  const sourceInstanceFingerprint = stringValue(record.sourceInstanceFingerprint);
+  const createdAt = stringValue(record.createdAt);
+  const updatedAt = stringValue(record.updatedAt);
+  if (
+    !id || !remoteUrl || !targetOrigin || !targetHost || !stackId || !targetCompanyId ||
+    !accessToken || !token || !privateKeyPem || !sourcePublicKey || !sourceInstanceId ||
+    !sourceInstanceFingerprint || !createdAt || !updatedAt
+  ) {
+    return null;
+  }
+  return {
+    id,
+    remoteUrl,
+    targetOrigin,
+    targetHost,
+    stackId,
+    stackSlug: stringValue(record.stackSlug),
+    stackDisplayName: stringValue(record.stackDisplayName),
+    targetCompanyId,
+    accessToken,
+    token,
+    privateKeyPem,
+    sourcePublicKey,
+    sourceInstanceId,
+    sourceInstanceFingerprint,
+    scopes: stringArray(record.scopes),
+    createdAt,
+    updatedAt,
+  };
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}

cli/src/commands/client/cloud-transfer.ts

@@ -0,0 +1,297 @@
+import { createHash } from "node:crypto";
+
+export const upstreamTransferSchema = {
+  family: "paperclip-upstream-transfer",
+  version: "1.0.0",
+  major: 1,
+  minor: 0,
+} as const;
+
+export type NormalizedSha256 = `sha256:${string}`;
+
+export interface SourceEntityKey {
+  sourceInstanceId: string;
+  sourceCompanyId: string;
+  sourceEntityType: string;
+  sourceEntityId: string;
+  sourceNaturalKey?: string;
+}
+
+export interface UpstreamTransferWarning {
+  code: string;
+  severity: "info" | "warning" | "blocker";
+  message: string;
+  entity?: SourceEntityKey;
+}
+
+export interface UpstreamTransferEntityRecord {
+  key: SourceEntityKey;
+  contentHash: NormalizedSha256;
+  dependencies: SourceEntityKey[];
+  warnings: UpstreamTransferWarning[];
+}
+
+export interface UpstreamTransferManifestSource {
+  sourceInstanceId: string;
+  sourceCompanyId: string;
+  sourceInstanceKeyFingerprint: string;
+  exporterVersion: string;
+  sourceSchemaVersion: string;
+}
+
+export interface UpstreamTransferManifestTarget {
+  targetStackId: string;
+  targetCompanyId: string;
+  targetOrigin: string;
+  supportedSchemaMajor: number;
+}
+
+export interface UpstreamTransferChunk {
+  chunkIndex: number;
+  totalChunks: number;
+  byteLength: number;
+  sha256: NormalizedSha256;
+  manifestHash: NormalizedSha256;
+}
+
+export interface UpstreamTransferManifest {
+  schema: typeof upstreamTransferSchema;
+  source: UpstreamTransferManifestSource;
+  target: UpstreamTransferManifestTarget;
+  runId: string;
+  idempotencyKey: string;
+  generatedAt: string;
+  entityCount: number;
+  entities: UpstreamTransferEntityRecord[];
+  chunks: UpstreamTransferChunk[];
+  warnings: UpstreamTransferWarning[];
+  featureFlags: string[];
+  manifestHash: NormalizedSha256;
+}
+
+export interface LocalUpstreamExportEntityInput {
+  key: SourceEntityKey;
+  body: Record<string, unknown>;
+  dependencies?: SourceEntityKey[];
+  warnings?: UpstreamTransferWarning[];
+  conflictKeys?: string[];
+}
+
+export interface LocalUpstreamExportEntity {
+  record: UpstreamTransferEntityRecord;
+  body: Record<string, unknown>;
+  conflictKeys?: string[];
+}
+
+export interface LocalUpstreamExportChunk {
+  chunkIndex: number;
+  totalChunks: number;
+  byteLength: number;
+  sha256: NormalizedSha256;
+  payload: {
+    entityKeys: SourceEntityKey[];
+  };
+}
+
+export interface LocalUpstreamExportBundle {
+  manifest: UpstreamTransferManifest;
+  entities: LocalUpstreamExportEntity[];
+  chunks: LocalUpstreamExportChunk[];
+}
+
+export interface BuildLocalUpstreamExportBundleInput {
+  source: UpstreamTransferManifestSource;
+  target: UpstreamTransferManifestTarget;
+  runId: string;
+  idempotencyKey: string;
+  entities: LocalUpstreamExportEntityInput[];
+  warnings?: UpstreamTransferWarning[];
+  featureFlags?: string[];
+  maxEntitiesPerChunk?: number;
+}
+
+export interface LocalUpstreamPushCoordinatorOptions {
+  targetOrigin: string;
+  paperclipCompanyId: string;
+  fetch?: typeof fetch;
+  headers?: (input: { method: string; path: string }) => HeadersInit | Promise<HeadersInit>;
+}
+
+export class UpstreamImportRequestError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(status: number, message: string, body: unknown) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class LocalUpstreamPushCoordinator {
+  readonly #targetOrigin: string;
+  readonly #paperclipCompanyId: string;
+  readonly #fetch: typeof fetch;
+  readonly #headers: NonNullable<LocalUpstreamPushCoordinatorOptions["headers"]>;
+
+  constructor(options: LocalUpstreamPushCoordinatorOptions) {
+    this.#targetOrigin = options.targetOrigin.replace(/\/+$/u, "");
+    this.#paperclipCompanyId = options.paperclipCompanyId;
+    this.#fetch = options.fetch ?? fetch;
+    this.#headers = options.headers ?? (() => ({}));
+  }
+
+  async preview(bundle: LocalUpstreamExportBundle): Promise<unknown> {
+    return this.post(`/api/companies/${encodeURIComponent(this.#paperclipCompanyId)}/upstream-imports/preview`, {
+      manifest: bundle.manifest,
+      entities: bundle.entities,
+    });
+  }
+
+  async apply(bundle: LocalUpstreamExportBundle): Promise<unknown> {
+    const run = await this.post(`/api/companies/${encodeURIComponent(this.#paperclipCompanyId)}/upstream-imports/runs`, {
+      mode: "apply",
+      manifest: bundle.manifest,
+      entities: bundle.entities,
+    }) as { run?: { id?: unknown } };
+    const runId = typeof run.run?.id === "string" ? run.run.id : undefined;
+    if (!runId) {
+      throw new Error("Remote upstream importer did not return a run id");
+    }
+
+    for (const chunk of bundle.chunks) {
+      await this.post(`/api/upstream-import-runs/${encodeURIComponent(runId)}/chunks`, chunk);
+    }
+
+    return this.post(`/api/upstream-import-runs/${encodeURIComponent(runId)}/apply`, {});
+  }
+
+  async events(runId: string): Promise<unknown> {
+    return this.get(`/api/upstream-import-runs/${encodeURIComponent(runId)}/events`);
+  }
+
+  private async get(path: string): Promise<unknown> {
+    const response = await this.#fetch(`${this.#targetOrigin}${path}`, {
+      method: "GET",
+      headers: await this.#headers({ method: "GET", path }),
+    });
+    return parseCoordinatorResponse(response);
+  }
+
+  private async post(path: string, body: unknown): Promise<unknown> {
+    const response = await this.#fetch(`${this.#targetOrigin}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...(await this.#headers({ method: "POST", path })),
+      },
+      body: JSON.stringify(body),
+    });
+    return parseCoordinatorResponse(response);
+  }
+}
+
+export function buildLocalUpstreamExportBundle(
+  input: BuildLocalUpstreamExportBundleInput,
+): LocalUpstreamExportBundle {
+  const entities = input.entities.map<LocalUpstreamExportEntity>((entity) => ({
+    record: {
+      key: entity.key,
+      contentHash: normalizedContentHash(entity.body),
+      dependencies: entity.dependencies ?? [],
+      warnings: entity.warnings ?? [],
+    },
+    body: entity.body,
+    conflictKeys: entity.conflictKeys,
+  }));
+  const chunks = buildLocalChunks(entities, input.maxEntitiesPerChunk ?? 100);
+  const manifestWithoutHash = {
+    schema: upstreamTransferSchema,
+    source: input.source,
+    target: input.target,
+    runId: input.runId,
+    idempotencyKey: input.idempotencyKey,
+    generatedAt: new Date(0).toISOString(),
+    entityCount: entities.length,
+    entities: entities.map((entity) => entity.record),
+    chunks: chunks.map(({ payload: _payload, ...chunk }) => chunk),
+    warnings: input.warnings ?? [],
+    featureFlags: (input.featureFlags ?? ["cloud_sync"]).slice().sort(),
+  };
+  const manifestHash = normalizedContentHash(manifestWithoutHash);
+  return {
+    manifest: {
+      ...manifestWithoutHash,
+      chunks: manifestWithoutHash.chunks.map((chunk) => ({ ...chunk, manifestHash })),
+      manifestHash,
+    },
+    entities,
+    chunks,
+  };
+}
+
+export function normalizedContentHash(value: unknown): NormalizedSha256 {
+  return `sha256:${createHash("sha256").update(canonicalJson(value)).digest("hex")}`;
+}
+
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortJson(value));
+}
+
+function buildLocalChunks(
+  entities: LocalUpstreamExportEntity[],
+  maxEntitiesPerChunk: number,
+): LocalUpstreamExportChunk[] {
+  if (!Number.isInteger(maxEntitiesPerChunk) || maxEntitiesPerChunk < 1) {
+    throw new Error("maxEntitiesPerChunk must be a positive integer");
+  }
+  if (entities.length === 0) return [];
+
+  const groups: LocalUpstreamExportEntity[][] = [];
+  for (let index = 0; index < entities.length; index += maxEntitiesPerChunk) {
+    groups.push(entities.slice(index, index + maxEntitiesPerChunk));
+  }
+
+  return groups.map((group, index) => {
+    const payload = {
+      entityKeys: group.map((entity) => entity.record.key),
+    };
+    return {
+      chunkIndex: index,
+      totalChunks: groups.length,
+      byteLength: Buffer.byteLength(canonicalJson(payload)),
+      sha256: normalizedContentHash(payload),
+      payload,
+    };
+  });
+}
+
+function sortJson(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (typeof value !== "object" || value === null) return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, sortJson(entry)]),
+  );
+}
+
+async function parseCoordinatorResponse(response: Response): Promise<unknown> {
+  const text = await response.text();
+  const parsed = text.trim() ? safeParseJson(text) : {};
+  if (!response.ok) {
+    const message = typeof parsed === "object" && parsed !== null && "error" in parsed
+      ? String((parsed as { error: unknown }).error)
+      : `Upstream importer request failed with ${response.status}`;
+    throw new UpstreamImportRequestError(response.status, message, parsed);
+  }
+  return parsed;
+}
+
+function safeParseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}

cli/src/commands/client/cloud.ts

@@ -0,0 +1,721 @@
+import { createHash, generateKeyPairSync, randomBytes, randomUUID, sign } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import { URL } from "node:url";
+import { Command } from "commander";
+import pc from "picocolors";
+import type {
+  CompanyPortabilityExportResult,
+  CompanyPortabilityFileEntry,
+  InstanceExperimentalSettings,
+} from "@paperclipai/shared";
+import { openUrl } from "../../client/board-auth.js";
+import { resolvePaperclipInstanceId } from "../../config/home.js";
+import {
+  addCommonClientOptions,
+  handleCommandError,
+  printOutput,
+  resolveCommandContext,
+  type BaseClientOptions,
+} from "./common.js";
+import {
+  buildLocalUpstreamExportBundle,
+  LocalUpstreamPushCoordinator,
+  normalizedContentHash,
+  upstreamTransferSchema,
+  UpstreamImportRequestError,
+  type LocalUpstreamExportBundle,
+  type LocalUpstreamExportEntityInput,
+  type SourceEntityKey,
+  type UpstreamTransferManifestSource,
+  type UpstreamTransferManifestTarget,
+  type UpstreamTransferWarning,
+} from "./cloud-transfer.js";
+import {
+  getCloudConnection,
+  upsertCloudConnection,
+  type CloudConnection,
+  type CloudConnectionTokenRecord,
+} from "./cloud-store.js";
+
+const CLOUD_SYNC_CONFLICT_EXIT_CODE = 2;
+const CLOUD_SYNC_SCHEMA_MISMATCH_EXIT_CODE = 3;
+const CLOUD_SYNC_SCOPES = ["upstream_import:preview", "upstream_import:write", "upstream_import:read"];
+const DEVICE_CODE_FALLBACK_EXPIRES_MS = 15 * 60_000;
+
+interface CloudConnectOptions extends BaseClientOptions {
+  noBrowser?: boolean;
+}
+
+interface CloudPushOptions extends BaseClientOptions {
+  company?: string;
+  remoteUrl?: string;
+  dryRun?: boolean;
+  maxEntitiesPerChunk?: number;
+}
+
+interface UpstreamDiscovery {
+  schema: string;
+  stack: {
+    id: string;
+    slug?: string;
+    displayName?: string;
+    companyId: string;
+    origin: string;
+  };
+  auth: {
+    pkce?: {
+      authorizeUrl: string;
+      tokenUrl: string;
+      codeChallengeMethod: string;
+    };
+    deviceCode?: {
+      deviceCodeUrl: string;
+      verificationUrl: string;
+      tokenUrl: string;
+    };
+    scopes?: string[];
+  };
+  transfer: {
+    supportedSchemaMajor: number;
+    featureFlags?: string[];
+  };
+}
+
+interface TokenResponse {
+  accessToken: string;
+  token: CloudConnectionTokenRecord;
+  scopes?: string[];
+  expiresAt?: string;
+}
+
+class CloudAuthRequestError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(status: number, message: string, body: unknown) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export function registerCloudCommands(program: Command): void {
+  const cloud = program.command("cloud").description("Paperclip Cloud upstream sync commands");
+
+  addCommonClientOptions(
+    cloud
+      .command("connect")
+      .description("Authorize this local instance to push into a Paperclip Cloud stack")
+      .argument("<remote-url>", "Paperclip Cloud stack URL")
+      .option("--no-browser", "Use the device-code flow instead of opening a browser", false)
+      .action(async (remoteUrl: string, opts: CloudConnectOptions) => {
+        try {
+          await connectCloud(remoteUrl, opts);
+        } catch (err) {
+          handleCommandError(err);
+        }
+      }),
+  );
+
+  addCommonClientOptions(
+    cloud
+      .command("push")
+      .description("Preview or apply a local company push into the connected Paperclip Cloud stack")
+      .requiredOption("--company <local-company-id>", "Local company ID to export")
+      .option("--remote-url <remote-url>", "Use a specific stored cloud connection")
+      .option("--dry-run", "Preview without applying", false)
+      .option("--max-entities-per-chunk <count>", "Chunk size for upstream uploads", (value) => Number(value), 100)
+      .action(async (opts: CloudPushOptions) => {
+        try {
+          await pushCloud(opts);
+        } catch (err) {
+          if (isSchemaMismatchError(err)) {
+            console.error(pc.red(err instanceof Error ? err.message : String(err)));
+            process.exitCode = CLOUD_SYNC_SCHEMA_MISMATCH_EXIT_CODE;
+            return;
+          }
+          handleCommandError(err);
+        }
+      }),
+  );
+}
+
+export async function connectCloud(remoteUrl: string, opts: CloudConnectOptions = {}): Promise<CloudConnection> {
+  const ctx = resolveCommandContext(opts);
+  const discovery = await discoverUpstream(remoteUrl);
+  assertDiscoveryCompatible(discovery);
+  const source = createSourceIdentity();
+  const token = await authorizeConnection(discovery, source, {
+    noBrowser: Boolean(opts.noBrowser),
+  });
+  const targetOrigin = discovery.stack.origin.replace(/\/+$/u, "");
+  const targetHost = new URL(targetOrigin).host;
+  const now = new Date().toISOString();
+  const connection = upsertCloudConnection({
+    id: connectionId(targetOrigin),
+    remoteUrl,
+    targetOrigin,
+    targetHost,
+    stackId: discovery.stack.id,
+    stackSlug: discovery.stack.slug ?? null,
+    stackDisplayName: discovery.stack.displayName ?? null,
+    targetCompanyId: discovery.stack.companyId,
+    accessToken: token.accessToken,
+    token: token.token,
+    privateKeyPem: source.privateKeyPem,
+    sourcePublicKey: source.sourcePublicKey,
+    sourceInstanceId: source.sourceInstanceId,
+    sourceInstanceFingerprint: source.sourceInstanceFingerprint,
+    scopes: token.scopes ?? token.token.scopes ?? CLOUD_SYNC_SCOPES,
+    createdAt: now,
+    updatedAt: now,
+  });
+
+  if (ctx.json) {
+    printOutput(redactConnection(connection), { json: true });
+  } else {
+    console.log(pc.bold("Connected to Paperclip Cloud"));
+    console.log(`stack=${connection.stackDisplayName ?? connection.stackSlug ?? connection.stackId}`);
+    console.log(`origin=${connection.targetOrigin}`);
+    console.log(`company=${connection.targetCompanyId}`);
+  }
+  return connection;
+}
+
+export async function pushCloud(opts: CloudPushOptions): Promise<unknown> {
+  const ctx = resolveCommandContext(opts, { requireCompany: false });
+  const localCompanyId = requiredString(opts.company, "--company");
+  await assertCloudSyncEnabled(ctx.api.get<InstanceExperimentalSettings>("/api/instance/settings/experimental"));
+  const connection = getCloudConnection(opts.remoteUrl);
+  if (!connection) {
+    throw new Error("No cloud connection found. Run `paperclipai cloud connect <remote-url>` first.");
+  }
+
+  const discovery = await discoverUpstream(connection.targetOrigin);
+  assertDiscoveryCompatible(discovery);
+  const bundle = await buildBundleFromLocalCompany({
+    localCompanyId,
+    connection,
+    discovery,
+    localApi: ctx.api,
+    maxEntitiesPerChunk: opts.maxEntitiesPerChunk,
+    mode: opts.dryRun ? "preview" : "apply",
+  });
+  const coordinator = new LocalUpstreamPushCoordinator({
+    targetOrigin: connection.targetOrigin,
+    paperclipCompanyId: connection.targetCompanyId,
+    headers: ({ method, path }) => cloudProofHeaders(connection, method, path),
+  });
+
+  const result = opts.dryRun ? await coordinator.preview(bundle) : await coordinator.apply(bundle);
+  const runId = getRunId(result);
+  const events = !opts.dryRun && runId ? await coordinator.events(runId).catch(() => null) : null;
+  const summary = summarizeResult(result);
+  const conflictCount = summary.conflict + summary.staleMapping;
+
+  if (ctx.json) {
+    printOutput({ result, events }, { json: true });
+  } else {
+    console.log(pc.bold(opts.dryRun ? "Cloud Push Preview" : "Cloud Push Applied"));
+    console.log(`run=${runId ?? "-"}`);
+    console.log(`manifest=${bundle.manifest.manifestHash}`);
+    console.log(
+      `create=${summary.create} update=${summary.update} adopt=${summary.adopt} ` +
+        `skip=${summary.skip} conflict=${summary.conflict} staleMapping=${summary.staleMapping}`,
+    );
+    printWarnings(result);
+    printConflicts(result);
+    printEvents(events);
+  }
+
+  if (conflictCount > 0) {
+    process.exitCode = CLOUD_SYNC_CONFLICT_EXIT_CODE;
+  }
+  return result;
+}
+
+export async function discoverUpstream(remoteUrl: string): Promise<UpstreamDiscovery> {
+  const base = new URL(remoteUrl);
+  const discoveryUrl = new URL("/.well-known/paperclip-upstream", base);
+  return requestCloudJson<UpstreamDiscovery>(discoveryUrl.toString(), { method: "GET" });
+}
+
+export function assertDiscoveryCompatible(discovery: UpstreamDiscovery): void {
+  if (discovery.schema !== "paperclip-upstream-discovery-v1") {
+    throw new Error("Remote URL is not a Paperclip Cloud upstream target.");
+  }
+  if (discovery.transfer.supportedSchemaMajor !== upstreamTransferSchema.major) {
+    throw new Error(
+      `Cloud upstream schema mismatch: local major ${upstreamTransferSchema.major}, remote supports ${discovery.transfer.supportedSchemaMajor}.`,
+    );
+  }
+  if (!discovery.transfer.featureFlags?.includes("cloud_sync")) {
+    throw new Error("Remote Paperclip Cloud stack does not advertise the cloud_sync transfer flag.");
+  }
+}
+
+export function resolveDeviceCodeExpiresAt(expiresAt: string | undefined, nowMs = Date.now()): number {
+  const parsed = typeof expiresAt === "string" ? Date.parse(expiresAt) : NaN;
+  return Number.isFinite(parsed) ? parsed : nowMs + DEVICE_CODE_FALLBACK_EXPIRES_MS;
+}
+
+export async function buildBundleFromLocalCompany(input: {
+  localCompanyId: string;
+  connection: CloudConnection;
+  discovery: UpstreamDiscovery;
+  localApi: {
+    post<T>(path: string, body?: unknown): Promise<T | null>;
+  };
+  maxEntitiesPerChunk?: number;
+  mode: "preview" | "apply";
+}): Promise<LocalUpstreamExportBundle> {
+  const exported = await input.localApi.post<CompanyPortabilityExportResult>(
+    `/api/companies/${input.localCompanyId}/export`,
+    {
+      include: {
+        company: true,
+        agents: true,
+        projects: true,
+        issues: true,
+        skills: true,
+      },
+      expandReferencedSkills: true,
+    },
+  );
+  if (!exported) throw new Error("Local company export returned no data.");
+
+  const sourceHash = normalizedContentHash({
+    manifest: exported.manifest,
+    files: exported.files,
+  });
+  const source: UpstreamTransferManifestSource = {
+    sourceInstanceId: input.connection.sourceInstanceId,
+    sourceCompanyId: input.localCompanyId,
+    sourceInstanceKeyFingerprint: input.connection.sourceInstanceFingerprint,
+    exporterVersion: "paperclipai-cli-cloud-v1",
+    sourceSchemaVersion: "paperclip-local-portability-v1",
+  };
+  const target: UpstreamTransferManifestTarget = {
+    targetStackId: input.discovery.stack.id,
+    targetCompanyId: input.discovery.stack.companyId,
+    targetOrigin: input.discovery.stack.origin,
+    supportedSchemaMajor: input.discovery.transfer.supportedSchemaMajor,
+  };
+  const entities = buildEntitiesFromPortableExport(input.localCompanyId, input.connection.sourceInstanceId, exported);
+  const idempotencyKey = [
+    input.mode,
+    input.connection.sourceInstanceId,
+    input.localCompanyId,
+    input.discovery.stack.id,
+    sourceHash,
+  ].join(":");
+  return buildLocalUpstreamExportBundle({
+    source,
+    target,
+    runId: `local-${input.mode}-${shortHash(idempotencyKey)}`,
+    idempotencyKey,
+    entities,
+    warnings: exported.warnings.map((message): UpstreamTransferWarning => ({
+      code: "local_company_export_warning",
+      severity: "warning",
+      message,
+    })),
+    featureFlags: ["cloud_sync"],
+    maxEntitiesPerChunk: input.maxEntitiesPerChunk,
+  });
+}
+
+async function authorizeConnection(
+  discovery: UpstreamDiscovery,
+  source: ReturnType<typeof createSourceIdentity>,
+  opts: { noBrowser: boolean },
+): Promise<TokenResponse> {
+  if (!opts.noBrowser && canOpenBrowser() && discovery.auth.pkce) {
+    try {
+      return await authorizeWithBrowser(discovery, source);
+    } catch (error) {
+      console.error(pc.yellow(`Browser authorization failed; falling back to device-code flow. ${errorMessage(error)}`));
+    }
+  }
+  if (!discovery.auth.deviceCode) {
+    throw new Error("Remote Paperclip Cloud stack does not support device-code authorization.");
+  }
+  return authorizeWithDeviceCode(discovery, source, { openBrowser: !opts.noBrowser && canOpenBrowser() });
+}
+
+async function authorizeWithBrowser(
+  discovery: UpstreamDiscovery,
+  source: ReturnType<typeof createSourceIdentity>,
+): Promise<TokenResponse> {
+  const pkce = discovery.auth.pkce;
+  if (!pkce) throw new Error("Remote did not advertise PKCE authorization.");
+  const callback = await startPkceCallbackServer();
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  const state = randomUUID();
+  const authorizeUrl = new URL(pkce.authorizeUrl);
+  authorizeUrl.searchParams.set("redirectUri", callback.redirectUri);
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("codeChallenge", challenge);
+  authorizeUrl.searchParams.set("codeChallengeMethod", "S256");
+  authorizeUrl.searchParams.set("sourceInstanceId", source.sourceInstanceId);
+  authorizeUrl.searchParams.set("sourceInstanceFingerprint", source.sourceInstanceFingerprint);
+  authorizeUrl.searchParams.set("sourcePublicKey", source.sourcePublicKey);
+  authorizeUrl.searchParams.set("scopes", CLOUD_SYNC_SCOPES.join(" "));
+
+  try {
+    console.error(`Open this URL to approve cloud sync:\n${authorizeUrl.toString()}`);
+    if (!openUrl(authorizeUrl.toString())) {
+      throw new Error("Could not open a browser.");
+    }
+    const code = await callback.waitForCode(state);
+    return requestCloudJson<TokenResponse>(pkce.tokenUrl, {
+      method: "POST",
+      body: JSON.stringify({
+        grantType: "authorization_code",
+        code,
+        redirectUri: callback.redirectUri,
+        codeVerifier: verifier,
+      }),
+    });
+  } finally {
+    await callback.close();
+  }
+}
+
+async function authorizeWithDeviceCode(
+  discovery: UpstreamDiscovery,
+  source: ReturnType<typeof createSourceIdentity>,
+  opts: { openBrowser: boolean },
+): Promise<TokenResponse> {
+  const device = discovery.auth.deviceCode;
+  if (!device) throw new Error("Remote did not advertise device-code authorization.");
+  const response = await requestCloudJson<{
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    expiresAt?: string;
+    intervalSeconds?: number;
+  }>(device.deviceCodeUrl, {
+    method: "POST",
+    body: JSON.stringify({
+      stackId: discovery.stack.id,
+      sourceInstanceId: source.sourceInstanceId,
+      sourceInstanceFingerprint: source.sourceInstanceFingerprint,
+      sourcePublicKey: source.sourcePublicKey,
+      scopes: CLOUD_SYNC_SCOPES,
+    }),
+  });
+  console.error(pc.bold("Cloud device authorization required"));
+  console.error(`Open: ${response.verificationUri}`);
+  console.error(`Code: ${response.userCode}`);
+  if (opts.openBrowser) openUrl(response.verificationUri);
+
+  const expiresAt = resolveDeviceCodeExpiresAt(response.expiresAt);
+  const intervalMs = Math.max(500, (response.intervalSeconds ?? 5) * 1000);
+  while (Date.now() < expiresAt) {
+    await sleep(intervalMs);
+    try {
+      return await requestCloudJson<TokenResponse>(device.tokenUrl, {
+        method: "POST",
+        body: JSON.stringify({
+          grantType: "device_code",
+          deviceCode: response.deviceCode,
+        }),
+      });
+    } catch (error) {
+      if (error instanceof CloudAuthRequestError && error.body && typeof error.body === "object") {
+        const code = (error.body as { error?: unknown }).error;
+        if (code === "authorization_pending") continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error("Device-code authorization expired before it was approved.");
+}
+
+function buildEntitiesFromPortableExport(
+  localCompanyId: string,
+  sourceInstanceId: string,
+  exported: CompanyPortabilityExportResult,
+): LocalUpstreamExportEntityInput[] {
+  const companyKey: SourceEntityKey = {
+    sourceInstanceId,
+    sourceCompanyId: localCompanyId,
+    sourceEntityType: "company",
+    sourceEntityId: localCompanyId,
+    sourceNaturalKey: exported.manifest.company?.name ?? localCompanyId,
+  };
+  const entities: LocalUpstreamExportEntityInput[] = [
+    {
+      key: companyKey,
+      body: {
+        kind: "paperclip_company_portability_manifest",
+        manifest: exported.manifest,
+        rootPath: exported.rootPath,
+        paperclipExtensionPath: exported.paperclipExtensionPath,
+        fileCount: Object.keys(exported.files).length,
+      },
+      conflictKeys: [`company:${companyKey.sourceNaturalKey ?? localCompanyId}`],
+    },
+  ];
+
+  for (const [filePath, entry] of Object.entries(exported.files).sort(([left], [right]) => left.localeCompare(right))) {
+    entities.push({
+      key: {
+        sourceInstanceId,
+        sourceCompanyId: localCompanyId,
+        sourceEntityType: "company_setting",
+        sourceEntityId: shortHash(filePath),
+        sourceNaturalKey: filePath,
+      },
+      body: {
+        kind: "paperclip_portable_file",
+        path: filePath,
+        entry: normalizePortableFileEntry(entry),
+      },
+      dependencies: [companyKey],
+      conflictKeys: [`portable_file:${filePath}`],
+    });
+  }
+  return entities;
+}
+
+function normalizePortableFileEntry(entry: CompanyPortabilityFileEntry): Record<string, unknown> {
+  if (typeof entry === "string") {
+    return { encoding: "utf8", data: entry };
+  }
+  return { ...entry };
+}
+
+async function assertCloudSyncEnabled(settingsPromise: Promise<InstanceExperimentalSettings | null>): Promise<void> {
+  const settings = await settingsPromise;
+  if (settings?.enableCloudSync !== true) {
+    throw new Error(
+      "Cloud sync is disabled. Enable the cloud sync experimental setting before running `paperclipai cloud push`.",
+    );
+  }
+}
+
+function cloudProofHeaders(connection: CloudConnection, method: string, pathAndSearch: string): Record<string, string> {
+  const timestamp = new Date().toISOString();
+  const nonce = randomUUID();
+  const payload = [
+    method,
+    connection.targetHost.toLowerCase(),
+    pathAndSearch,
+    connection.token.id,
+    connection.sourceInstanceId,
+    timestamp,
+    nonce,
+  ].join("\n");
+  return {
+    Authorization: `Bearer ${connection.accessToken}`,
+    "X-Paperclip-Upstream-Source-Instance-Id": connection.sourceInstanceId,
+    "X-Paperclip-Upstream-Proof-Timestamp": timestamp,
+    "X-Paperclip-Upstream-Proof-Nonce": nonce,
+    "X-Paperclip-Upstream-Proof-Signature": sign(
+      null,
+      Buffer.from(payload, "utf8"),
+      connection.privateKeyPem,
+    ).toString("base64url"),
+  };
+}
+
+async function requestCloudJson<T>(url: string, init: RequestInit): Promise<T> {
+  const headers = new Headers(init.headers);
+  headers.set("accept", "application/json");
+  if (init.body !== undefined && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  const response = await fetch(url, { ...init, headers });
+  const text = await response.text();
+  const parsed = text.trim() ? JSON.parse(text) as unknown : {};
+  if (!response.ok) {
+    const message = typeof parsed === "object" && parsed !== null && "error" in parsed
+      ? String((parsed as { error: unknown }).error)
+      : `Cloud request failed with ${response.status}`;
+    throw new CloudAuthRequestError(response.status, message, parsed);
+  }
+  return parsed as T;
+}
+
+function createSourceIdentity() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const sourcePublicKey = publicKey.export({ type: "spki", format: "pem" }).toString();
+  const sourceInstanceFingerprint = `sha256:${createHash("sha256")
+    .update(publicKey.export({ type: "spki", format: "der" }))
+    .digest("hex")}`;
+  return {
+    sourceInstanceId: `paperclip-local-${resolvePaperclipInstanceId()}`,
+    sourceInstanceFingerprint,
+    sourcePublicKey,
+    privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+  };
+}
+
+async function startPkceCallbackServer(): Promise<{
+  redirectUri: string;
+  waitForCode: (state: string) => Promise<string>;
+  close: () => Promise<void>;
+}> {
+  let resolveCode: ((code: string) => void) | null = null;
+  let rejectCode: ((error: Error) => void) | null = null;
+  let expectedState = "";
+  const codePromise = new Promise<string>((resolve, reject) => {
+    resolveCode = resolve;
+    rejectCode = reject;
+  });
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    if (!code || state !== expectedState) {
+      res.writeHead(400, { "Content-Type": "text/plain" });
+      res.end("Paperclip Cloud authorization failed. You can close this tab.");
+      rejectCode?.(new Error("Authorization callback was missing a valid code or state."));
+      return;
+    }
+    res.writeHead(200, { "Content-Type": "text/plain" });
+    res.end("Paperclip Cloud authorization complete. You can close this tab.");
+    resolveCode?.(code);
+  });
+  await listenOnLoopback(server);
+  const address = server.address();
+  if (typeof address !== "object" || !address?.port) {
+    throw new Error("Failed to start local authorization callback server.");
+  }
+  return {
+    redirectUri: `http://127.0.0.1:${address.port}/cloud/callback`,
+    waitForCode: (state: string) => {
+      expectedState = state;
+      return codePromise;
+    },
+    close: () => closeServer(server),
+  };
+}
+
+function listenOnLoopback(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+}
+
+function closeServer(server: Server): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => error ? reject(error) : resolve());
+  });
+}
+
+function canOpenBrowser(): boolean {
+  if (process.platform === "darwin" || process.platform === "win32") return true;
+  return Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+}
+
+function summarizeResult(result: unknown): {
+  create: number;
+  update: number;
+  adopt: number;
+  skip: number;
+  conflict: number;
+  staleMapping: number;
+} {
+  const summary = asRecord(asRecord(result)?.summary);
+  return {
+    create: numberValue(summary?.create),
+    update: numberValue(summary?.update),
+    adopt: numberValue(summary?.adopt),
+    skip: numberValue(summary?.skip),
+    conflict: numberValue(summary?.conflict),
+    staleMapping: numberValue(summary?.staleMapping),
+  };
+}
+
+function printWarnings(result: unknown): void {
+  const warnings = Array.isArray(asRecord(result)?.warnings) ? asRecord(result)?.warnings as unknown[] : [];
+  for (const warning of warnings) {
+    const record = asRecord(warning);
+    console.log(pc.yellow(`warning=${record?.code ?? "warning"} ${record?.message ?? ""}`.trim()));
+  }
+}
+
+function printConflicts(result: unknown): void {
+  const conflicts = Array.isArray(asRecord(result)?.conflicts) ? asRecord(result)?.conflicts as unknown[] : [];
+  for (const conflict of conflicts.slice(0, 10)) {
+    const record = asRecord(conflict);
+    console.log(pc.red(`conflict=${record?.conflictKind ?? "target_conflict"} target=${record?.targetEntityId ?? "-"}`));
+  }
+  if (conflicts.length > 10) console.log(pc.red(`conflicts_truncated=${conflicts.length - 10}`));
+}
+
+function printEvents(events: unknown): void {
+  const rows = Array.isArray(asRecord(events)?.events) ? asRecord(events)?.events as unknown[] : [];
+  for (const row of rows.slice(-10)) {
+    const event = asRecord(row);
+    console.log(pc.dim(`event=${event?.action ?? "-"} target=${event?.targetEntityId ?? "-"}`));
+  }
+}
+
+function getRunId(result: unknown): string | null {
+  const run = asRecord(asRecord(result)?.run);
+  return typeof run?.id === "string" ? run.id : null;
+}
+
+function redactConnection(connection: CloudConnection): Record<string, unknown> {
+  return {
+    id: connection.id,
+    remoteUrl: connection.remoteUrl,
+    targetOrigin: connection.targetOrigin,
+    stackId: connection.stackId,
+    targetCompanyId: connection.targetCompanyId,
+    scopes: connection.scopes,
+    expiresAt: connection.token.expiresAt,
+  };
+}
+
+function connectionId(targetOrigin: string): string {
+  return `cloud-${shortHash(targetOrigin)}`;
+}
+
+function shortHash(value: string): string {
+  return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+function requiredString(value: unknown, label: string): string {
+  if (typeof value === "string" && value.trim()) return value.trim();
+  throw new Error(`${label} is required.`);
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function isSchemaMismatchError(error: unknown): boolean {
+  if (error instanceof UpstreamImportRequestError) {
+    return JSON.stringify(error.body).toLowerCase().includes("schema");
+  }
+  return error instanceof Error && error.message.toLowerCase().includes("schema mismatch");
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export const cloudCommandExitCodes = {
+  conflict: CLOUD_SYNC_CONFLICT_EXIT_CODE,
+  schemaMismatch: CLOUD_SYNC_SCHEMA_MISMATCH_EXIT_CODE,
+} as const;

cli/src/commands/routines.ts

@@ -9,6 +9,7 @@ import {
   createEmbeddedPostgresLogBuffer,
   ensurePostgresDatabase,
   formatEmbeddedPostgresError,
+  prepareEmbeddedPostgresNativeRuntime,
   routines,
 } from "@paperclipai/db";
 import { eq, inArray } from "drizzle-orm";
@@ -116,6 +117,7 @@ async function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): P
       "Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.",
     );
   }
+  await prepareEmbeddedPostgresNativeRuntime();
 
   const postmasterPidFile = path.resolve(dataDir, "postmaster.pid");
   const runningPid = readRunningPostmasterPid(postmasterPidFile);

cli/src/commands/worktree.ts

@@ -45,6 +45,7 @@ import {
   runDatabaseRestore,
   createEmbeddedPostgresLogBuffer,
   formatEmbeddedPostgresError,
+  prepareEmbeddedPostgresNativeRuntime,
 } from "@paperclipai/db";
 import type { Command } from "commander";
 import { ensureAgentJwtSecret, loadPaperclipEnvFile, mergePaperclipEnvEntries, readPaperclipEnvEntries, resolvePaperclipEnvFile } from "../config/env.js";
@@ -1059,6 +1060,7 @@ async function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): P
       "Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.",
     );
   }
+  await prepareEmbeddedPostgresNativeRuntime();
 
   const postmasterPidFile = path.resolve(dataDir, "postmaster.pid");
   const runningPid = readRunningPostmasterPid(postmasterPidFile);
@@ -1385,7 +1387,12 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
   }
 
   if (opts.force) {
-    rmSync(paths.repoConfigDir, { recursive: true, force: true });
+    // Only remove the specific files we're about to rewrite, not the whole
+    // repoConfigDir — that directory can contain sibling state such as
+    // <repo>/.paperclip/worktrees/ holding every repo-managed worktree
+    // checkout, and a recursive rmSync here would nuke them all.
+    rmSync(paths.configPath, { force: true });
+    rmSync(paths.envPath, { force: true });
     rmSync(paths.instanceRoot, { recursive: true, force: true });
   }
 

cli/src/index.ts

@@ -19,6 +19,7 @@ import { registerDashboardCommands } from "./commands/client/dashboard.js";
 import { registerRoutineCommands } from "./commands/routines.js";
 import { registerFeedbackCommands } from "./commands/client/feedback.js";
 import { registerSecretCommands } from "./commands/client/secrets.js";
+import { registerCloudCommands } from "./commands/client/cloud.js";
 import { applyDataDirOverride, type DataDirOptionLike } from "./config/data-dir.js";
 import { loadPaperclipEnvFile } from "./config/env.js";
 import { initTelemetryFromConfigFile, flushTelemetry } from "./telemetry.js";
@@ -149,6 +150,7 @@ registerDashboardCommands(program);
 registerRoutineCommands(program);
 registerFeedbackCommands(program);
 registerSecretCommands(program);
+registerCloudCommands(program);
 registerWorktreeCommands(program);
 registerEnvLabCommands(program);
 registerPluginCommands(program);

doc/DATABASE.md

@@ -143,6 +143,17 @@ The database mode is controlled by `DATABASE_URL`:
 
 Your Drizzle schema (`packages/db/src/schema/`) stays the same regardless of mode.
 
+## Resource membership tables
+
+Paperclip stores current-user sidebar membership state in:
+
+- `project_memberships`
+- `agent_memberships`
+
+These rows are company-scoped and user-scoped. A missing row means the user is joined, so existing users keep seeing projects and agents in the sidebar until they explicitly leave them. Rows only control sidebar visibility; they do not affect project/agent detail access, all-pages, selectors, assignment flows, or existing company permissions.
+
+Both tables use a unique key on `(company_id, user_id, resource_id)` and keep `state` as `joined` or `left`. Join/leave mutations are idempotent board-user `/me` operations and write activity entries when the effective state changes.
+
 ## Plugin database namespaces
 
 The plugin runtime tracks plugin-owned database namespaces and migrations in `plugin_database_namespaces` and `plugin_migrations`. Hosted deployments that separate runtime and migration connections should set `DATABASE_MIGRATION_URL`; plugin namespace migration work uses the migration connection when present.
@@ -165,6 +176,10 @@ Paperclip stores secret metadata and versions in:
 
 - `company_secrets`
 - `company_secret_versions`
+- `company_secret_bindings`
+- `secret_access_events`
+
+Secret-aware env bindings are supported by agents, projects, and routines. Routine env lives in `routines.env`, is captured in `routine_revisions.snapshot`, and routine dispatches store `routine_runs.routine_revision_id` so runtime secret resolution uses the env snapshot that existed when the run was created. Routine secret refs bind with `target_type = 'routine'`, `target_id = routines.id`, and `config_path` values under `env.*`.
 
 For local/default installs, the active provider is `local_encrypted`:
 

doc/DEVELOPING.md

@@ -554,10 +554,12 @@ pnpm paperclipai dashboard get
 
 See full command reference in `doc/CLI.md`.
 
-## OpenClaw Invite Onboarding Endpoints
+## Agent Invite Onboarding Endpoints
 
 Agent-oriented invite onboarding now exposes machine-readable API docs:
 
+The board UI generates agent onboarding prompts from the add-agent modal (`+` in the agent sidebar), so agent onboarding sits with the rest of agent creation rather than company member invite settings.
+
 - `GET /api/invites/:token` returns invite summary plus onboarding and skills index links.
 - `GET /api/invites/:token/onboarding` returns onboarding manifest details (registration endpoint, claim endpoint template, skill install hints).
 - `GET /api/invites/:token/onboarding.txt` returns a plain-text onboarding doc intended for both human operators and agents (llm.txt-style handoff), including optional inviter message and suggested network host candidates.
@@ -575,7 +577,7 @@ pnpm smoke:openclaw-join
 What it validates:
 
 - invite creation for agent-only join
-- agent join request using `adapterType=openclaw`
+- agent join request using `adapterType=openclaw_gateway`
 - board approval + one-time API key claim semantics
 - callback delivery on wakeup to a dockerized OpenClaw-style webhook receiver
 

doc/PRODUCT.md

@@ -118,6 +118,7 @@ Paperclip’s core identity is a **control plane for autonomous AI companies**,
 - Do not make the core product a general chat app. The current product definition is explicitly task/comment-centric and “not a chatbot,” and that boundary is valuable.
 - Do not build a complete Jira/GitHub replacement. The repo/docs already position Paperclip as organization orchestration, not focused on pull-request review.
 - Do not build enterprise-grade RBAC first. Paperclip now has authenticated mode, company memberships, instance roles, and permission grants, but fine-grained enterprise governance should remain secondary to the core company control plane.
+- Do not interpret agent-level privacy flags as a project/issue privacy feature in V1; work visibility stays company-scoped.
 - Do not lead with raw bash logs and transcripts. Default view should be human-readable intent/progress, with raw detail beneath.
 - Do not force users to understand provider/API-key plumbing unless absolutely necessary. There are active onboarding/auth issues already; friction here is clearly real.
 

doc/SPEC-implementation.md

@@ -34,7 +34,7 @@ These decisions close open questions from `SPEC.md` for V1.
 | Company model | Company is first-order; all business entities are company-scoped |
 | Board | Single human board operator per deployment |
 | Org graph | Strict tree (`reports_to` nullable root); no multi-manager reporting |
-| Visibility | Full visibility to board and all agents in same company |
+| Visibility | Company-scoped visibility: board + all in-company agents can see all work objects by default; public/private deployment flags affect external exposure only and do **not** imply project/issue privacy |
 | Communication | Tasks + comments only (no separate chat system) |
 | Task ownership | Single assignee; atomic checkout required for `in_progress` transition |
 | Recovery | Liveness/watchdog recovery preserves explicit ownership: retry lost execution continuity where safe, otherwise open visible source-scoped recovery actions by default, use issue-backed recovery only for independent repair work, or require human escalation (see `doc/execution-semantics.md`) |
@@ -207,6 +207,8 @@ Invariant:
 
 - project env is merged into run environment for issues in that project and overrides conflicting agent env keys before Paperclip runtime-owned keys are injected
 
+Routine execution issues add a routine-scoped env overlay after project env and before Paperclip runtime-owned keys. Routine env uses the same secret-aware binding format, is stored on `routines.env`, is snapshotted in routine revisions, and resolves secret refs against the routine binding target so routine-owned secrets do not require direct bindings on the executing agent.
+
 ## 7.6 `issues` (core task entity)
 
 - `id` uuid pk
@@ -309,7 +311,32 @@ Invariant: each event must attach to agent and company; rollups are aggregation,
 - `details` jsonb null
 - `created_at` timestamptz not null default now()
 
-## 7.12 `company_secrets` + `company_secret_versions`
+## 7.12 `project_memberships` + `agent_memberships`
+
+Per-user project/agent membership is personal visibility state for board users. It only controls whether a resource appears in the current user's sidebar; it must not grant or revoke access to all-pages, detail pages, selectors, assignment flows, search, or existing permissions.
+
+`project_memberships`:
+
+- `id` uuid pk
+- `company_id` uuid fk `companies.id` not null
+- `project_id` uuid fk `projects.id` not null
+- `user_id` text not null
+- `state` enum-like text: `joined | left`
+- `created_at` timestamptz not null default now()
+- `updated_at` timestamptz not null default now()
+- unique `(company_id, user_id, project_id)`
+
+`agent_memberships` mirrors the same shape with `agent_id` instead of `project_id` and unique `(company_id, user_id, agent_id)`.
+
+Invariants:
+
+- Missing membership rows mean `joined` for backward compatibility.
+- Mutations are board-user-only `/me` operations; agent API keys are rejected.
+- Viewer-role board users may update only their own membership rows through the narrow self-service helper.
+- Target project/agent ownership is checked against the path company before mutation.
+- Successful state changes write `resource_membership.joined` or `resource_membership.left` activity entries.
+
+## 7.13 `company_secrets` + `company_secret_versions`
 
 - Secret values are not stored inline in `agents.adapter_config.env`.
 - Agent env entries should use secret refs for sensitive values.
@@ -323,7 +350,7 @@ Operational policy:
 - Activity and approval payloads must not persist raw sensitive values.
 - Config revisions may include redacted placeholders; such revisions are non-restorable for redacted fields.
 
-## 7.13 Required Indexes
+## 7.14 Required Indexes
 
 - `agents(company_id, status)`
 - `agents(company_id, reports_to)`
@@ -341,8 +368,12 @@ Operational policy:
 - `issue_attachments(company_id, issue_id)`
 - `company_secrets(company_id, name)` unique
 - `company_secret_versions(secret_id, version)` unique
+- `project_memberships(company_id, user_id)`
+- `project_memberships(company_id, user_id, project_id)` unique
+- `agent_memberships(company_id, user_id)`
+- `agent_memberships(company_id, user_id, agent_id)` unique
 
-## 7.14 `assets` + `issue_attachments`
+## 7.15 `assets` + `issue_attachments`
 
 - `assets` stores provider-backed object metadata (not inline bytes):
   - `id` uuid pk
@@ -376,6 +407,10 @@ Operational policy:
   - `created_by_user_id` uuid/text fk null
   - `updated_by_agent_id` uuid fk null
   - `updated_by_user_id` uuid/text fk null
+  - `locked_at` timestamptz null
+  - `locked_by_agent_id` uuid fk null
+  - `locked_by_user_id` uuid/text fk null
+  - Locked documents are immutable until unlocked. Board operators can lock/unlock; agent writes to a locked key create a new issue document with a derived key instead of overwriting the locked document.
 - `document_revisions` stores append-only history:
   - `id` uuid pk
   - `company_id` uuid fk not null
@@ -396,7 +431,7 @@ The current implementation includes additional V1-control-plane tables beyond th
 
 - Issue structure and review: `issue_relations` for blockers, `labels`/`issue_labels`, `issue_thread_interactions`, `issue_approvals`, `issue_execution_decisions`, `issue_work_products`, `issue_inbox_archives`, `issue_read_states`, and issue reference mention indexes.
 - Execution and workspace control: `execution_workspaces`, `project_workspaces`, `workspace_runtime_services`, `workspace_operations`, `environments`, `environment_leases`, `agent_task_sessions`, `agent_runtime_state`, `agent_wakeup_requests`, heartbeat events, and watchdog decision tables.
-- Plugins and routines: `plugins`, plugin config/state/entities/jobs/logs/webhooks, plugin database namespaces/migrations, plugin company settings, and `routines`.
+- Plugins and routines: `plugins`, plugin config/state/entities/jobs/logs/webhooks, plugin database namespaces/migrations, plugin company settings, `routines`, `routine_revisions`, `routine_triggers`, and `routine_runs`.
 - Access and operations: company memberships, instance roles, principal permission grants, invites, join requests, board API keys, CLI auth challenges, budget policies/incidents, feedback exports/votes, company skills, sidebar preferences, and company logos.
 
 ## 8. State Machines
@@ -481,6 +516,59 @@ Detailed ownership, execution, blocker, active-run watchdog, crash-recovery, and
 | Report cost | yes | yes |
 | Set company budget | yes | no |
 | Set subordinate budget | yes | yes (manager subtree only) |
+| Set work-object visibility (issue/project) | no | no (pro gate) |
+
+## 9.4 Permission Terminology and Default Visibility Rule
+
+Paperclip V1 keeps a company-scoped visibility model as the default because centralized authorization and scoped work-object controls are not yet a core V1 control surface.
+
+The approved term set is:
+
+- **Agent profile visibility**: identity-level facts needed for delegation and governance (name, role, capabilities, reporting lines).
+- **Agent config visibility**: adapter/runtime config metadata and secret-access policy.
+- **Assignment/invocation permission**: who may modify or execute a task.
+- **Work-object visibility**: who can read/write issues, comments, projects, and attachments.
+- **Tool/secret policy**: what tools and secret-backed credentials an agent can use and what appears in logs.
+- **Escalation authority**: where refusal/blocked decisions route (manager, then board).
+
+## 9.5 Core V1 Rule: what “private” means
+
+- A **private marker** on an agent profile (where represented) does **not** make company-visible work private.
+- Company-visible work objects (issues, comments, work products, costs, activity, project/task state) remain visible to the board and in-company agents by default.
+- Project/issue-level privacy, scoped assignment-only object visibility, and organization-wide custom ACLs are deferred to Pro/Enterprise controls.
+
+## 9.6 V1 vs Pro/Enterprise Controls (recommended target split)
+
+| Permission area | Free / V1 default | Pro / Enterprise |
+|---|---|---|
+| Company boundary | Hard boundary only (`company_id`) | Multi-company policy overlays (`membership`, `project`, and `task` scopes) |
+| Simple roles | Board + agent roles with existing approval/budget gates | Additional role aliases + scoped approver roles |
+| Profile visibility | Full profile visibility for coordination and audit | Optional profile redaction / selective sharing for external surfaces |
+| Config visibility | Board full read with redacted secret fields; agent config read/write constrained by own agent identity | Scoped config visibility controls and central policy enforcement |
+| Assignment/invocation | Assignment creates execution authority; board can reassign or force release | Delegation policies and scoped invokers with deny-listed tool classes |
+| Work-object visibility | All issues and projects in-company are visible to board and agents | Project/issue ACLs and reviewer-only channels |
+| Tool/secret policy | Secret refs, log redaction, and adapter-level command/webhook restrictions | Tool allowlists with centralized policy evaluation |
+| Escalation | Escalate from agent to manager to board; board approval/budget gates remain authoritative | Escalation routing and SLA windows |
+
+## 9.7 Recommended first-slice implementation order
+
+1. Lock route-level checks for existing company boundaries, actor extraction, and approval/budget gates.
+2. Treat profile privacy as external-facing signal only; do not use it to hide company-visible work objects.
+3. Enforce assignment/invocation coupling (`assignee`/`agent` checks, checkout semantics, invocation checks).
+4. Standardize read-path redaction for secrets and secret references, including logs and activity.
+5. Standardize escalation paths (`blocked` and refusal) so non-board agents hand off by manager/board with immutable audit.
+
+## 9.8 Scoped Task Assignment Grants
+
+`tasks:assign` remains the broad assignment permission. Existing unscoped grants preserve compatibility and allow the principal to assign any visible company task within normal company-boundary checks.
+
+`tasks:assign_scope` is the constrained assignment permission. Its `principal_permission_grants.scope` JSON must include at least one recognized constraint:
+
+- Project scope: `projectId`, `projectIds`, or `allow: ["project:<projectId>"]`.
+- Target-agent allowlist: `agentId`, `agentIds`, `assigneeAgentId`, `assigneeAgentIds`, `targetAgentId`, `targetAgentIds`, or `allow: ["agent:<agentId>"]`.
+- Managed-subtree scope: `managerAgentId`, `managerAgentIds`, `managedSubtreeAgentId`, `managedSubtreeAgentIds`, `subtreeAgentId`, `subtreeAgentIds`, `subtreeRootAgentId`, `subtreeRootAgentIds`, or `allow: ["subtree:<agentId>"]`.
+
+When multiple constraint families are present, assignment must satisfy all of them. Denials return `403` with a generic scope explanation and do not disclose details about hidden or unrelated resources.
 
 ## 10. API Contract (REST)
 
@@ -524,6 +612,8 @@ All endpoints are under `/api` and return JSON.
 - `GET /issues/:issueId/documents`
 - `GET /issues/:issueId/documents/:key`
 - `PUT /issues/:issueId/documents/:key`
+- `POST /issues/:issueId/documents/:key/lock`
+- `POST /issues/:issueId/documents/:key/unlock`
 - `GET /issues/:issueId/documents/:key/revisions`
 - `DELETE /issues/:issueId/documents/:key`
 - `POST /issues/:issueId/checkout`
@@ -562,14 +652,28 @@ Server behavior:
 - `GET /projects/:projectId`
 - `PATCH /projects/:projectId`
 
-## 10.6 Approvals
+## 10.6 Current-user Resource Memberships
+
+- `GET /companies/:companyId/resource-memberships/me`
+- `PUT /companies/:companyId/resource-memberships/me/projects/:projectId`
+- `PUT /companies/:companyId/resource-memberships/me/agents/:agentId`
+
+Request payload:
+
+```json
+{ "state": "joined" }
+```
+
+Allowed states are `joined` and `left`. Endpoints require a concrete board user and active company membership, reject agent API keys, and only mutate the caller's own sidebar visibility state. Joining/leaving is idempotent; missing rows read as `joined`.
+
+## 10.7 Approvals
 
 - `GET /companies/:companyId/approvals?status=pending`
 - `POST /companies/:companyId/approvals`
 - `POST /approvals/:approvalId/approve`
 - `POST /approvals/:approvalId/reject`
 
-## 10.7 Cost and Budgets
+## 10.8 Cost and Budgets
 
 - `POST /companies/:companyId/cost-events`
 - `GET /companies/:companyId/costs/summary`
@@ -578,7 +682,7 @@ Server behavior:
 - `PATCH /companies/:companyId/budgets`
 - `PATCH /agents/:agentId/budgets`
 
-## 10.8 Activity and Dashboard
+## 10.9 Activity and Dashboard
 
 - `GET /companies/:companyId/activity`
 - `GET /companies/:companyId/dashboard`
@@ -590,7 +694,7 @@ Dashboard payload must include:
 - month-to-date spend and budget utilization
 - pending approvals count
 
-## 10.9 Error Semantics
+## 10.10 Error Semantics
 
 - `400` validation error
 - `401` unauthenticated
@@ -600,7 +704,7 @@ Dashboard payload must include:
 - `422` semantic rule violation
 - `500` server error
 
-## 10.10 Current Implementation API Addenda
+## 10.11 Current Implementation API Addenda
 
 The current app also exposes V1-supporting surfaces for:
 
@@ -671,7 +775,13 @@ Behavior:
 - `thin`: send IDs and pointers only; agent fetches context via API
 - `fat`: include current assignments, goal summary, budget snapshot, and recent comments
 
-## 11.5 Scheduler Rules
+## 11.5 Recovery Model Profiles
+
+The optional `modelProfiles.cheap` lane is not a retry worker lane. Paperclip may request the cheap profile only for status-only recovery coordination, and those wakes must include guard context that prevents deliverable work and document/plan updates (`allowDeliverableWork: false`, `allowDocumentUpdates: false`, `resumeRequiresNormalModel: true`).
+
+Failed source-work retries, process-loss retries, transient/scheduled retries, max-turn continuations, source-assignee continuations, and downstream source-work child/requeue/resume contexts must use the normal/original model lane. If cheap recovery repairs liveness while actual work remains, the next live continuation path must be a separate normal-model worker run with cheap hints scrubbed.
+
+## 11.6 Scheduler Rules
 
 Per-agent schedule fields in `adapter_config`:
 

doc/SPEC.md

@@ -141,6 +141,8 @@ Hierarchical reporting structure. CEO at top, reports cascade down.
 
 **Full visibility across the org.** Every agent can see the entire org chart, all tasks, all agents. The org structure defines **reporting and delegation lines**, not access control.
 
+Visibility settings on an agent profile (where supported) do not alter company-level visibility for tasks, projects, issues, comments, costs, or activity. Those work-object privacy controls are not a V1 feature until centralized scoped authorization is in place.
+
 Each agent publishes a short description of their responsibilities and capabilities — almost like skills ("when I'm relevant"). This lets other agents discover who can help with what.
 
 ### Cross-Team Work

doc/execution-semantics.md

@@ -184,7 +184,7 @@ A valid recovery action must name:
 - the wake, monitor, timeout, retry, or escalation policy that will move the action forward
 - the resolution outcome when closed, such as restored, delegated, false positive, blocked, escalated, or cancelled
 
-A source-scoped recovery action is the default form. Use it when the next safe move is to repair the source issue's liveness directly: restore a wake path, clarify disposition, re-establish a monitor, record a false positive, or delegate real follow-up work from the source issue.
+A source-scoped recovery action is the default form. Use it when the next safe move is to repair the source issue's liveness directly: move the source issue back to `todo` so it can be retried, clarify disposition, re-establish a monitor, record a false positive, or delegate real follow-up work from the source issue.
 
 Use an issue-backed recovery action only when the recovery is genuinely independent work or when source-scoped handling would be unsafe or unclear. Examples include:
 
@@ -196,6 +196,14 @@ Use an issue-backed recovery action only when the recovery is genuinely independ
 
 A comment or system notice can be evidence for a recovery action, but it is not a recovery action by itself. Comment-only recovery is not a healthy liveness path because it does not define a typed owner, wake or monitor policy, retry bound, timeout, escalation path, or resolution outcome.
 
+#### Recovery action freshness
+
+Source-scoped recovery actions are snapshots of the source issue's liveness state at the time the action was opened. They must be revalidated after newer durable source activity, including source issue status changes, assignee changes, blocker changes, execution policy or monitor changes, document or work-product updates that define a valid waiting path, and structured resume or disposition updates.
+
+When newer source activity restores a valid live or waiting path, the recovery action is stale and should be folded through the explicit recovery lifecycle instead of being hidden or deleted. Folding means resolving or cancelling the recovery action with a resolution outcome and note that preserve the audit trail.
+
+Plain comments alone do not make a recovery action stale. A comment can provide evidence, but the recovery action should remain visible when the source issue is still stalled and the comment does not create a valid action-path primitive such as a wake, monitor, interaction, approval, blocker, human owner, execution participant, terminal disposition, or delegated follow-up.
+
 ### Agent-assigned `todo`
 
 This is dispatch state: ready to start, not yet actively claimed.
@@ -322,18 +330,25 @@ Recovery rule:
 
 This is an active-work continuity recovery.
 
+### 8.3 Recovery model-profile lane
+
+Cheap model profiles are only for status-only operational recovery overhead. Paperclip may request `modelProfile: "cheap"` for bounded recovery-owner work that updates task liveness, clears bad status, records a disposition, or asks for human/manager intervention. Those wakes must carry guard context such as `allowDeliverableWork: false`, `allowDocumentUpdates: false`, and `resumeRequiresNormalModel: true`.
+
+Automatic retries that can continue source work must use the original/normal model lane. This includes failed source-work retries, process-loss retries, transient/scheduled retries, max-turn continuations, source-assignee continuations, assigned-todo dispatch recovery, and any run that can update repo files, issue documents, plans, work products, or attachments. When a cheap status-only recovery determines that actual work remains, it must hand back to a normal-model worker run before source work or persistent deliverable updates resume. Cheap recovery hints must be scrubbed from copied retry, resume, child, and downstream source-work contexts.
+
 ## 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 four things in sequence:
+On startup and on the periodic recovery loop, Paperclip now does five things in sequence:
 
 1. reap orphaned `running` runs
 2. resume persisted `queued` runs
 3. reconcile stranded assigned work
-4. scan silent active runs and create or update explicit watchdog recovery actions
+4. scan silent active runs, revalidate their source issues, and either fold source-resolved watchdogs or create/update explicit watchdog recovery actions
+5. reconcile productivity reviews
 
-The stranded-work pass closes the gap where issue state survives a crash but the wake/run path does not. The silent-run scan covers the separate case where a live process exists but has stopped producing observable output.
+The stranded-work pass closes the gap where issue state survives a crash but the wake/run path does not. The silent-run scan covers the separate case where a live process exists but has stopped producing observable output. The productivity-review pass is later and separate; it reviews unusual progression patterns on assigned source issues, not stale run handles after a source issue already has a valid disposition.
 
 ## 10. Silent Active-Run Watchdog
 
@@ -360,6 +375,33 @@ Operators should prefer `snooze` for known time-bounded quiet periods. `continue
 
 The board can record watchdog decisions. The assigned owner of an issue-backed watchdog evaluation can also record them. Other agents cannot.
 
+### Source-aware watchdog folding
+
+Active-run watchdog work is source-aware. Before the watchdog creates, refreshes, escalates, or blocks on reviewer work, it must re-read the linked source issue and decide whether the watchdog signal is still about productive source work or only about stale run/process bookkeeping.
+
+Fold watchdog work when all of these are true:
+
+- the run is linked to a source issue in the same company
+- the source issue is terminal (`done` or `cancelled`)
+- durable source activity from the same run proves the source issue reached that terminal disposition after the stale-run or output-silence evidence point
+- there is no independent evidence that the still-running or detached process is doing harmful work, still owns external cleanup that needs an operator decision, or needs a separate security/ownership review
+
+Folding means resolving or cancelling the watchdog recovery action or issue-backed evaluation through the explicit recovery lifecycle. It must preserve the run id, source issue, detected silence or detached-process evidence, terminal source activity, decision reason, and best-effort process cleanup result. It must be idempotent for the `(companyId, runId, sourceIssueId)` signal and must not recursively recover the watchdog evaluation issue itself.
+
+Do not fold watchdog work only because the run is quiet. The watchdog must still create or continue reviewer work when:
+
+- the source issue is still `todo` or `in_progress`, because productive work may still be happening or stuck
+- the source issue remains `in_progress` after a successful run with no valid disposition, because the successful-run handoff path owns that bounded correction
+- the run terminated or disappeared while the source issue remains `in_progress` without a live path, because stranded assigned recovery owns that continuity repair
+- the source issue is terminal but there is no durable same-run terminal activity after the stale evidence point
+- there is independent evidence that the process may still be mutating external state, leaking resources, crossing company or ownership boundaries, or otherwise needs operator review
+
+In the normal non-terminal case, critical silence can still create issue-backed evaluation work and block the source issue when blocking is necessary for correctness. In the source-resolved case, a completed source issue should not acquire a new manager review or blocker merely because an old run handle stayed active; only real unresolved work should block work.
+
+This is distinct from productivity review. Productivity review asks whether an assigned source issue has unusual progression patterns, such as no-comment terminal-run streaks, long active duration, or high churn. Source-resolved watchdog folding asks whether a stale active-run signal outlived a source issue that already reached a valid terminal disposition. One does not substitute for the other.
+
+Detached process cleanup is operational hygiene, not source issue liveness. Cleanup should be best-effort and auditable. If cleanup fails but the source issue is already terminal with same-run durable evidence, Paperclip should preserve the cleanup failure on the run/watchdog audit trail and route only the cleanup concern to bounded recovery when a real owner/action remains.
+
 ## 11. Auto-Recover vs Explicit Recovery vs Human Escalation
 
 Paperclip uses three different recovery outcomes, depending on how much it can safely infer.

doc/plans/2026-05-05-scaled-kanban-board-design.md

@@ -0,0 +1,90 @@
+# Scaled Kanban Board Design
+
+Date: 2026-05-05
+Branch: `feat/scaled-kanban-board`
+
+## Context
+
+The Issues page currently supports list and board modes. List mode already has grouping, sorting, filtering, nested parent/child rows, deferred row rendering, and incremental render limits. Board mode uses classic status columns with draggable cards. It fetches per-status board data, but the current UI still presents each lane as an unbounded stack of cards, which becomes tall and heavy when a company has hundreds of issues.
+
+The goal is to keep the Kanban mental model while making high-volume boards usable. This is a UI-first change. It should not introduce schema changes or new API contracts in the first pass.
+
+## Problem
+
+When Paperclip has many issues, board columns get too tall and slow. The operator loses the ability to scan the board quickly, and rendering or dragging through long columns becomes unpleasant. The first version should solve this by reducing the number of visible cards per column and by collapsing low-signal columns, not by replacing Kanban with a different inventory surface.
+
+## Design
+
+Board mode remains status-column based. Each column shows its total issue count, a bounded set of visible cards, and a local affordance to reveal more cards in that column. The board should keep active workflow lanes expanded by default and collapse cold or noisy lanes once issue volume is high.
+
+Default high-volume behavior activates when the filtered board has more than 100 issues:
+
+- Compact cards are used by default.
+- `backlog`, `done`, and `cancelled` auto-collapse to narrow rails.
+- `todo`, `in_progress`, `in_review`, and `blocked` remain expanded by default.
+- Each expanded column renders an initial 10 cards by default.
+- The user can choose a page size of 10, 25, or 50 cards per column.
+- The user can reveal one additional page at a time in each column without changing other columns.
+- Drag and drop continues to work for visible cards.
+
+The toolbar should expose compact controls for:
+
+- toggling compact cards
+- hiding or showing cold lanes
+- choosing cards per column
+- resetting board density to defaults
+
+These preferences should persist through the existing issue view-state/localStorage mechanism and remain scoped by company.
+
+## Component Shape
+
+`IssuesList` remains the owner of issue board view state. It should store board-density preferences alongside the existing issue view state, including compact card preference, cold-lane mode, and cards-per-column page size.
+
+`KanbanBoard` receives board tuning props from `IssuesList` and delegates per-lane display to `KanbanColumn`.
+
+`KanbanColumn` owns only local presentation mechanics for a lane:
+
+- whether the lane is rendered as an expanded column or collapsed rail
+- how many cards are currently visible in that lane
+- the local "show more" action
+
+`KanbanCard` gets a compact variant. The compact card should still show the issue identifier, title, live state, priority, and assignee when available, but with tighter spacing and fewer vertical affordances.
+
+## Data Flow
+
+The first implementation uses the current issue data already available to board mode. No database, shared type, or route change is required.
+
+Column totals are computed from the in-memory filtered board issues. If a column reaches the existing remote board query cap, the existing warning remains the truth source that more filtering may be required.
+
+Future server-side column pagination can be added later if the UI-only version is not enough for very large instances.
+
+## Error Handling
+
+This feature should not introduce new network errors. Existing issue loading and update errors continue to surface through the Issues page.
+
+For drag and drop:
+
+- Moving a visible card keeps the current optimistic behavior.
+- Hidden cards remain hidden until revealed.
+- A collapsed lane rail is a valid drop target. Dropping onto it moves the issue to that status and keeps the lane collapsed.
+
+## Testing
+
+Focused tests should cover:
+
+- board mode passes density preferences into `KanbanBoard`
+- columns render only the initial visible card count
+- "show more" reveals more cards in a single column
+- high-volume cold lanes render as collapsed rails by default
+- compact cards preserve identifier/title/live/priority/assignee signals
+- drag/drop status updates still call `onUpdateIssue`
+
+Manual verification should include opening the Issues board with a large fixture or mocked issue set and confirming that columns remain usable with hundreds of issues.
+
+## Out of Scope
+
+- Server-side per-column pagination
+- New issue schema fields
+- Replacing Kanban with a dense table or action-only board
+- Changing issue status semantics
+- Broad visual redesign of the Issues page

doc/plans/2026-05-05-scaled-kanban-board.md

@@ -0,0 +1,250 @@
+# Scaled Kanban Board Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the Issues Kanban board usable with hundreds of issues by adding compact high-volume rendering, collapsed cold lanes, and per-column reveal controls.
+
+**Architecture:** Keep the change UI-only. `IssuesList` owns persisted board density preferences in existing company-scoped view state, while `KanbanBoard` owns lane rendering, card density, collapsed rails, and per-column "show more" state.
+
+**Tech Stack:** React 19, TypeScript, Vite, Vitest/jsdom, `@dnd-kit/core`, `@dnd-kit/sortable`, Tailwind utility classes.
+
+---
+
+## File Structure
+
+- Modify `ui/src/components/IssuesList.tsx`: extend `IssueViewState`, derive high-volume board preferences, add toolbar controls, pass props into `KanbanBoard`.
+- Modify `ui/src/components/KanbanBoard.tsx`: add compact cards, collapsed rail lanes, visible-card limits, and per-column reveal behavior.
+- Create `ui/src/components/KanbanBoard.test.tsx`: focused tests for high-volume behavior and drag/drop update callback.
+- Modify `ui/src/components/IssuesList.test.tsx`: update the mocked `KanbanBoard` expectations for new props.
+- Keep `doc/plans/2026-05-05-scaled-kanban-board-design.md` as the design source of truth.
+
+## Task 1: Add Kanban Board Scaling Mechanics
+
+**Files:**
+- Modify: `ui/src/components/KanbanBoard.tsx`
+- Create: `ui/src/components/KanbanBoard.test.tsx`
+
+- [ ] **Step 1: Write focused tests**
+
+Create `ui/src/components/KanbanBoard.test.tsx` with tests that render 60 todo issues and assert:
+
+```tsx
+renderBoard({ issues: createIssues(60, "todo"), compactCards: true, initialVisibleCount: 10, revealIncrement: 10 });
+expect(container.textContent).toContain("Showing 10 of 60");
+expect(container.textContent).toContain("Show 10 more");
+```
+
+Also test collapsed rails:
+
+```tsx
+renderBoard({ issues: createIssues(3, "done"), collapsedStatuses: ["done"] });
+expect(container.textContent).toContain("Done");
+expect(container.textContent).toContain("3");
+expect(container.textContent).not.toContain("Issue 1");
+```
+
+- [ ] **Step 2: Run tests to verify failure**
+
+Run:
+
+```bash
+pnpm exec vitest run ui/src/components/KanbanBoard.test.tsx
+```
+
+Expected: fail because `KanbanBoard.test.tsx` is new and the props/behavior do not exist.
+
+- [ ] **Step 3: Implement minimal board behavior**
+
+In `KanbanBoard.tsx`, add exported constants:
+
+```ts
+export const KANBAN_BOARD_HIGH_VOLUME_THRESHOLD = 100;
+export const KANBAN_COLUMN_PAGE_SIZE_OPTIONS = [10, 25, 50] as const;
+export const KANBAN_COLUMN_DEFAULT_PAGE_SIZE = 10;
+export const KANBAN_COLD_STATUSES = ["backlog", "done", "cancelled"] as const;
+```
+
+Extend props:
+
+```ts
+compactCards?: boolean;
+collapsedStatuses?: string[];
+initialVisibleCount?: number;
+revealIncrement?: number;
+```
+
+Add per-status visible-count state keyed by status. Expanded columns render `issues.slice(0, visibleCount)` and show a button when hidden issues remain. Collapsed columns render a narrow droppable rail with status icon, label, and count, but no cards.
+
+Reset per-status visible-count state when `initialVisibleCount` or `revealIncrement` changes so choosing a smaller cards-per-column preset does not leave a column expanded past the newly selected page size.
+
+- [ ] **Step 4: Preserve drag/drop**
+
+Keep `DndContext`, `SortableContext`, and `handleDragEnd` status detection. Because collapsed rails use `useDroppable({ id: status })`, dropping a visible card onto a rail continues to resolve `targetStatus` through the existing status-id branch.
+
+- [ ] **Step 5: Run focused test**
+
+Run:
+
+```bash
+pnpm exec vitest run ui/src/components/KanbanBoard.test.tsx
+```
+
+Expected: pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add ui/src/components/KanbanBoard.tsx ui/src/components/KanbanBoard.test.tsx
+git commit -m "Scale kanban board columns"
+```
+
+## Task 2: Wire Board Density State Into IssuesList
+
+**Files:**
+- Modify: `ui/src/components/IssuesList.tsx`
+- Modify: `ui/src/components/IssuesList.test.tsx`
+
+- [ ] **Step 1: Write/update tests**
+
+In `IssuesList.test.tsx`, update the `KanbanBoard` mock to capture:
+
+```ts
+compactCards?: boolean;
+collapsedStatuses?: string[];
+initialVisibleCount?: number;
+revealIncrement?: number;
+```
+
+Add a test that stores board mode in localStorage, renders more than 100 issues, and expects:
+
+```ts
+expect(mockKanbanBoard).toHaveBeenLastCalledWith(expect.objectContaining({
+  compactCards: true,
+  collapsedStatuses: expect.arrayContaining(["backlog", "done", "cancelled"]),
+  initialVisibleCount: 10,
+  revealIncrement: 10,
+}));
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run:
+
+```bash
+pnpm exec vitest run ui/src/components/IssuesList.test.tsx
+```
+
+Expected: fail because `IssuesList` does not pass the new props yet.
+
+- [ ] **Step 3: Add persisted board density preferences**
+
+Extend `IssueViewState`:
+
+```ts
+boardCardDensity: "auto" | "compact" | "comfortable";
+boardColdLaneMode: "auto" | "collapsed" | "expanded";
+boardColumnPageSize: 10 | 25 | 50;
+```
+
+Default the density modes to `"auto"` and page size to `10`. Derive:
+
+```ts
+const boardHighVolume = viewState.viewMode === "board" && filtered.length > KANBAN_BOARD_HIGH_VOLUME_THRESHOLD;
+const boardCompactCards = viewState.boardCardDensity === "compact"
+  || (viewState.boardCardDensity === "auto" && boardHighVolume);
+const boardCollapsedStatuses = viewState.boardColdLaneMode === "collapsed"
+  || (viewState.boardColdLaneMode === "auto" && boardHighVolume)
+    ? [...KANBAN_COLD_STATUSES]
+    : [];
+```
+
+- [ ] **Step 4: Add toolbar controls**
+
+When `viewState.viewMode === "board"`, add small outline/icon buttons near the existing view controls:
+
+```tsx
+<Button ... title={boardCompactCards ? "Use comfortable cards" : "Use compact cards"}>...</Button>
+<Button ... title={boardCollapsedStatuses.length > 0 ? "Expand cold lanes" : "Collapse cold lanes"}>...</Button>
+<Button ... title="Cards per column">...</Button>
+<Button ... title="Reset board density">...</Button>
+```
+
+Use lucide icons already available or import `ChevronsDownUp`, `PanelTopClose`, and `RotateCcw`.
+
+- [ ] **Step 5: Pass board props**
+
+Update the `KanbanBoard` call:
+
+```tsx
+<KanbanBoard
+  issues={filtered}
+  agents={agents}
+  liveIssueIds={liveIssueIds}
+  compactCards={boardCompactCards}
+  collapsedStatuses={boardCollapsedStatuses}
+  initialVisibleCount={viewState.boardColumnPageSize}
+  revealIncrement={viewState.boardColumnPageSize}
+  onUpdateIssue={onUpdateIssue}
+/>
+```
+
+- [ ] **Step 6: Run focused tests**
+
+Run:
+
+```bash
+pnpm exec vitest run ui/src/components/IssuesList.test.tsx ui/src/components/KanbanBoard.test.tsx
+```
+
+Expected: pass.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add ui/src/components/IssuesList.tsx ui/src/components/IssuesList.test.tsx
+git commit -m "Wire issue board density controls"
+```
+
+## Task 3: Verification And PR Prep
+
+**Files:**
+- Verify existing changes only.
+
+- [ ] **Step 1: Run targeted UI tests**
+
+```bash
+pnpm exec vitest run ui/src/components/IssuesList.test.tsx ui/src/components/KanbanBoard.test.tsx
+```
+
+Expected: pass.
+
+- [ ] **Step 2: Run broader cheap test path**
+
+```bash
+pnpm test
+```
+
+Expected: pass.
+
+- [ ] **Step 3: Check worktree**
+
+```bash
+git status --short
+```
+
+Expected: only intentional changes before committing, or clean after final commit.
+
+- [ ] **Step 4: Prepare PR**
+
+Read `.github/PULL_REQUEST_TEMPLATE.md` and use it for the PR body. Include:
+
+- design spec path
+- scaled Kanban behavior summary
+- test commands and results
+- Model Used section with the current Codex model details available in this session
+
+## Self-Review
+
+- Spec coverage: The plan covers compact high-volume board cards, collapsed cold lanes, cards-per-column presets, per-column reveal controls, persisted board preferences, current API reuse, and focused tests.
+- Placeholder scan: No unresolved markers or unspecified implementation placeholders remain.
+- Type consistency: The plan consistently uses `boardCardDensity`, `boardColdLaneMode`, `boardColumnPageSize`, `compactCards`, `collapsedStatuses`, `initialVisibleCount`, and `revealIncrement`.

doc/plugins/LOCAL_PLUGIN_DEVELOPMENT.md

@@ -2,7 +2,12 @@
 
 This is the short happy-path guide for developing a Paperclip plugin from a folder on your machine. You will scaffold a plugin, run it in watch mode, install it into a running Paperclip instance from an absolute local path, and edit code with the plugin worker reloading after each rebuild.
 
-For the full alpha surface — manifest fields, capabilities, managed agents/projects/routines, UI slots, scoped API routes — see [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md).
+For the full alpha surface — manifest fields, capabilities, managed agents/projects/routines/skills, UI slots, scoped API routes — see [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md).
+
+If your plugin has background-like recurring work, model it as managed resources:
+declare managed routines plus managed agents/projects/skills, then reconcile those
+resources in worker actions. This gives operators visible work items, budgets,
+pause controls, and consistent audits instead of hidden daemon behavior.
 
 ## Prerequisites
 
@@ -126,7 +131,8 @@ When you are done iterating locally, publish the package and reinstall the npm-p
 
 - **Restart cleanly:** `paperclipai plugin disable <key>` pauses the plugin without removing it. `paperclipai plugin enable <key>` brings it back. `paperclipai plugin uninstall <key>` removes the install record; add `--force` to also purge plugin state and settings.
 - **Browse examples:** `paperclipai plugin examples` lists the bundled example plugins that ship with the repo, each with a ready-to-run `paperclipai plugin install <path>` line.
-- **Go deeper:** [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md) covers worker capabilities, managed agents/projects/routines, plugin database namespaces, scoped API routes, and the shared UI components in `@paperclipai/plugin-sdk/ui`. [`PLUGIN_SPEC.md`](./PLUGIN_SPEC.md) is the longer-form specification, including future ideas that are not yet implemented.
+- **Go deeper:** [`PLUGIN_AUTHORING_GUIDE.md`](./PLUGIN_AUTHORING_GUIDE.md) covers worker capabilities, managed agents/projects/routines/skills, plugin database namespaces, scoped API routes, and the shared UI components in `@paperclipai/plugin-sdk/ui`. [`PLUGIN_SPEC.md`](./PLUGIN_SPEC.md) is the longer-form specification, including future ideas that are not yet implemented.
+- **Routine-first automation:** If your plugin should produce periodic issue work, prefer managed routines and `ctx.routines.managed` reconciliation over custom process loops or unobserved cron code.
 
 ## Troubleshooting
 

doc/plugins/PLUGIN_AUTHORING_GUIDE.md

@@ -13,6 +13,8 @@ It is intentionally narrower than [PLUGIN_SPEC.md](./PLUGIN_SPEC.md). The spec i
 - Worker-side host APIs are capability-gated.
 - Plugin UI is not sandboxed by manifest capabilities.
 - Plugin database migrations are restricted to a host-derived plugin namespace.
+- Plugin-managed surfaces are first-class records (agents, projects, routines, and
+  skills) rather than private plugin-only state.
 - Plugin-owned JSON API routes must be declared in the manifest and are mounted
   only under `/api/plugins/:pluginId/api/*`.
 - The host provides a small shared React component kit through
@@ -74,6 +76,7 @@ Worker:
 - issues, comments, namespaced `plugin:<pluginKey>` origins, blocker relations, checkout assertions, assignment wakeups, and orchestration summaries
 - agents, plugin-managed agents, and agent sessions
 - plugin-managed routines
+- plugin-managed skills
 - goals
 - data/actions
 - streams
@@ -134,11 +137,16 @@ paths; they always remain under `/api/plugins/:pluginId/api/*`.
 
 Plugins that provide durable Paperclip business objects should declare them in
 the manifest and let the host create or relink the actual records per company.
-Do this for plugin-owned agents, plugin-owned projects, and recurring automation.
+Do this for plugin-owned agents, projects, routines, and skills.
 Do not hide long-lived work behind private plugin state when it should be visible
 to the board, scoped to a company, audited, budgeted, and assigned like normal
 Paperclip work.
 
+Content-oriented plugins, such as LLM Wiki-style ingestion or durable knowledge
+systems, should use the same pattern: managed projects for operation issues,
+managed agents plus managed skills for LLM work, and managed routines for
+ingest, lint, refresh, or maintenance runs.
+
 Use these surfaces:
 
 - Managed agents: declare top-level `agents[]` and require
@@ -155,10 +163,14 @@ Use these surfaces:
   jobs that should create visible Paperclip issues. Prefer managed routines over
   plugin `jobs[]` for recurring business work; plugin jobs are for plugin
   runtime maintenance that does not need a board-visible task trail.
+- Managed skills: declare top-level `skills[]` and require `skills.managed`.
+  Use this for reusable plugin capabilities that should be surfaced to operators and
+  synced into Paperclip managed agents.
 
 Managed resources are resolved by stable plugin keys, not hardcoded database
 ids. In a worker action or data handler, call `ctx.agents.managed.reconcile()`,
-`ctx.projects.managed.reconcile()`, and `ctx.routines.managed.reconcile()` for
+`ctx.projects.managed.reconcile()`, `ctx.routines.managed.reconcile()`, and
+`ctx.skills.managed.reconcile()` for
 the current `companyId`. `reconcile()` creates the missing resource, relinks a
 recoverable binding, or returns the existing resource. `reset()` reapplies the
 manifest defaults when the operator wants to restore the plugin's suggested
@@ -185,6 +197,7 @@ const manifest: PaperclipPluginManifestV1 = {
     "agents.managed",
     "projects.managed",
     "routines.managed",
+    "skills.managed",
     "instance.settings.register",
   ],
   entrypoints: {
@@ -231,6 +244,13 @@ const manifest: PaperclipPluginManifestV1 = {
       ],
     },
   ],
+  skills: [
+    {
+      skillKey: "weekly-brief-skills",
+      displayName: "Weekly Briefer",
+      description: "Reusable skill for the managed research workflow.",
+    },
+  ],
   ui: {
     slots: [
       {
@@ -261,8 +281,9 @@ export default definePlugin({
       const project = await ctx.projects.managed.reconcile("research", companyId);
       const agent = await ctx.agents.managed.reconcile("researcher", companyId);
       const routine = await ctx.routines.managed.reconcile("weekly-brief", companyId);
+      const skill = await ctx.skills.managed.reconcile("weekly-brief-skills", companyId);
 
-      return { project, agent, routine };
+      return { project, agent, routine, skill };
     });
   },
 });
@@ -270,14 +291,18 @@ export default definePlugin({
 
 Authoring rules:
 
-- Keep keys stable once published. Renaming `agentKey`, `projectKey`, or
-  `routineKey` creates a new managed resource from the host's point of view.
+- Keep keys stable once published. Renaming `agentKey`, `projectKey`,
+  `routineKey`, or `skillKey` creates a new managed resource from the host's
+  point of view.
 - Use managed agents for plugin-provided labor. Use `ctx.agents.invoke()` or
   `ctx.agents.sessions` only after you have a real agent id, either selected by
   the operator or resolved from `ctx.agents.managed`.
 - Use managed routines for recurring or externally triggered work that should
   produce tasks. Schedule, webhook, and API triggers are visible routine
   triggers, and each run has the normal Paperclip issue/audit trail.
+- Use managed skills for reusable operator-visible capabilities that are shared
+  by managed agents. Reconcile skill declarations by `skillKey` and keep the
+  declared skill markdown and files in sync with agent behavior.
 - Use managed projects to keep plugin-generated work organized and to give
   project-scoped plugin UI a stable home. For filesystem access inside a
   project, still resolve project workspaces through `ctx.projects`.
@@ -300,6 +325,7 @@ Mount surfaces currently wired in the host include:
 - `settingsPage`
 - `dashboardWidget`
 - `sidebar`
+- `routeSidebar`
 - `sidebarPanel`
 - `detailTab`
 - `taskDetailView`
@@ -317,6 +343,10 @@ Paperclip-native control. The host owns the implementation, so plugins inherit
 the board's current styling, ordering, recent selections, and dark-mode behavior
 without importing `ui/src` internals.
 
+Prefer shared components for common Paperclip UX patterns to reduce drift and
+deprecation risk, especially for task/assignment flows and routine or sidebar-like
+plugin screens.
+
 Currently exposed components include:
 
 - `MarkdownBlock` and `MarkdownEditor` for rendered and editable markdown.

doc/plugins/PLUGIN_SPEC.md

@@ -319,7 +319,10 @@ export interface PaperclipPluginManifestV1 {
   version: string;
   displayName: string;
   description: string;
+  author: string;
   categories: Array<"connector" | "workspace" | "automation" | "ui">;
+  minimumHostVersion?: string;
+  /** @deprecated Use `minimumHostVersion` instead. Retained for backwards compatibility. */
   minimumPaperclipVersion?: string;
   capabilities: string[];
   entrypoints: {
@@ -335,15 +338,42 @@ export interface PaperclipPluginManifestV1 {
     description: string;
     parametersSchema: JsonSchema;
   }>;
+  database?: PluginDatabaseDeclaration;
+  apiRoutes?: PluginApiRouteDeclaration[];
+  environmentDrivers?: PluginEnvironmentDriverDeclaration[];
+  agents?: PluginManagedAgentDeclaration[];
+  projects?: PluginManagedProjectDeclaration[];
+  routines?: PluginManagedRoutineDeclaration[];
+  skills?: PluginManagedSkillDeclaration[];
+  localFolders?: PluginLocalFolderDeclaration[];
+  /** Legacy top-level launcher declarations. Prefer `ui.launchers` for new manifests. */
+  launchers?: PluginLauncherDeclaration[];
   ui?: {
+    launchers?: PluginLauncherDeclaration[];
     slots: Array<{
-      type: "page" | "detailTab" | "dashboardWidget" | "sidebar" | "settingsPage";
+      type: "page"
+        | "detailTab"
+        | "taskDetailView"
+        | "dashboardWidget"
+        | "sidebar"
+        | "routeSidebar"
+        | "sidebarPanel"
+        | "projectSidebarItem"
+        | "globalToolbarButton"
+        | "toolbarButton"
+        | "contextMenuItem"
+        | "commentAnnotation"
+        | "commentContextMenuItem"
+        | "settingsPage"
+        | "companySettingsPage";
       id: string;
       displayName: string;
       /** Which export name in the UI bundle provides this component */
       exportName: string;
       /** For detailTab: which entity types this tab appears on */
       entityTypes?: Array<"project" | "issue" | "agent" | "goal" | "run">;
+      /** For page and companySettingsPage: single route segment */
+      routePath?: string;
     }>;
   };
 }
@@ -354,10 +384,17 @@ Rules:
 - `id` must be globally unique
 - `id` should normally equal the npm package name
 - `apiVersion` must match the host-supported plugin API version
+- `minimumHostVersion` is preferred, with `minimumPaperclipVersion` retained for
+  backwards compatibility
 - `capabilities` must be static and install-time visible
 - config schema must be JSON Schema compatible
 - `entrypoints.ui` points to the directory containing the built UI bundle
 - `ui.slots` declares which extension slots the plugin fills, so the host knows what to mount without loading the bundle eagerly; each slot references an `exportName` from the UI bundle
+- declare managed declarations with the matching `*.managed` capability:
+  - `agents` → `agents.managed`
+  - `projects` → `projects.managed`
+  - `routines` → `routines.managed`
+  - `skills` → `skills.managed`
 
 ## 11. Agent Tools
 
@@ -631,6 +668,22 @@ Plugins that need filesystem, git, terminal, or process operations handle those
 
 Trusted orchestration plugins can create and update Paperclip issues through `ctx.issues` instead of importing server internals. The public issue contract includes parent/project/goal links, board or agent assignees, blocker IDs, labels, billing code, request depth, execution workspace inheritance, and plugin origin metadata.
 
+Plugins that perform durable work should declare managed Paperclip resources rather than using private plugin state:
+
+- `agents` + `ctx.agents.managed.*` for named, invokable operators (`agents.managed` required)
+- `projects` + `ctx.projects.managed.*` for stable, scoped issue/workspace ownership (`projects.managed` required)
+- `routines` + `ctx.routines.managed.*` for schedule/webhook/manual execution with issue trails (`routines.managed` required)
+- `skills` + `ctx.skills.managed.*` for reusable agent capabilities (`skills.managed` required)
+
+The LLM Wiki plugin is the current reference for this pattern: it declares managed
+agents, projects, routines, and skills in manifest, reconciles them per company,
+and uses managed routines for periodic wiki maintenance and ingest operations.
+Content-oriented plugins should follow the same model instead of running
+unmanaged background loops: make the LLM-facing worker an operator-visible
+managed agent, attach reusable prompt/tool guidance as managed skills, keep
+operation issues in a managed project, and drive recurring work through managed
+routines.
+
 Origin rules:
 
 - Built-in core issues keep built-in origins such as `manual` and `routine_execution`.
@@ -746,20 +799,38 @@ The host enforces capabilities in the SDK layer and refuses calls outside the gr
 - `activity.read`
 - `costs.read`
 - `issues.orchestration.read`
+- `database.namespace.read`
 
 ### Data Write
 
 - `issues.create`
 - `issues.update`
 - `issue.comments.create`
+- `issue.interactions.create`
 - `issue.documents.write`
 - `issue.relations.write`
 - `issues.checkout`
 - `issues.wakeup`
-- `assets.write`
-- `assets.read`
 - `activity.log.write`
 - `metrics.write`
+- `telemetry.track`
+- `assets.read`
+- `assets.write`
+- `database.namespace.migrate`
+- `database.namespace.write`
+- `goals.create`
+- `goals.update`
+- `projects.managed`
+- `routines.managed`
+- `skills.managed`
+- `agents.managed`
+- `agents.pause`
+- `agents.resume`
+- `agents.invoke`
+- `agent.sessions.create`
+- `agent.sessions.list`
+- `agent.sessions.send`
+- `agent.sessions.close`
 
 ### Plugin State
 
@@ -772,8 +843,10 @@ The host enforces capabilities in the SDK layer and refuses calls outside the gr
 - `events.emit`
 - `jobs.schedule`
 - `webhooks.receive`
+- `local.folders`
 - `http.outbound`
 - `secrets.read-ref`
+- `environment.drivers.register`
 
 ### Agent Tools
 
@@ -786,6 +859,7 @@ The host enforces capabilities in the SDK layer and refuses calls outside the gr
 - `ui.page.register`
 - `ui.detailTab.register`
 - `ui.dashboardWidget.register`
+- `ui.commentAnnotation.register`
 - `ui.action.register`
 
 ## 15.2 Forbidden Capabilities
@@ -894,6 +968,7 @@ Job rules:
 3. The host prevents overlapping execution of the same plugin/job combination unless explicitly allowed later.
 4. Every job run is recorded in Postgres.
 5. Failed jobs are retryable.
+6. For recurring business workflows that should create visible Paperclip work, prefer managed routines and managed resources over jobs. Jobs remain useful for private plugin-runtime maintenance tasks.
 
 ## 18. Webhooks
 
@@ -1134,6 +1209,8 @@ For plugins that need richer settings UX beyond what JSON Schema can express, th
 
 Both approaches coexist: a plugin can use the auto-generated form for simple config and add a custom settings page slot for advanced configuration or operational dashboards.
 
+For plugins that need a company-scoped settings surface, declare a `companySettingsPage` slot with a `routePath`. The host renders a sidebar item under Company Settings and mounts the component at `/:companyPrefix/company/settings/:routePath`. The page receives `companyId` and `companyPrefix` in its host context. Core settings routes such as `access`, `invites`, `environments`, and `secrets` are reserved and cannot be shadowed by plugin declarations.
+
 ## 20. Local Tooling
 
 Plugins that need filesystem, git, terminal, or process operations implement those directly. The host does not wrap or proxy these operations.
@@ -1383,6 +1460,14 @@ Each plugin may expose a company-context main page:
 
 This page is where board users do most day-to-day work.
 
+## 24.4 Company Settings Plugin Page
+
+Each ready plugin may expose a company settings page:
+
+- `/:companyPrefix/company/settings/:routePath`
+
+The host adds a matching Company Settings sidebar item using the slot `displayName`. Plugin settings route segments are single-segment slugs and must not collide with core company settings pages.
+
 ## 25. Uninstall And Data Lifecycle
 
 When a plugin is uninstalled, the host must handle plugin-owned data explicitly.

doc/spec/invite-flow.md

@@ -6,7 +6,7 @@ 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/components/NewAgentDialog.tsx`
 - `ui/src/pages/InviteLanding.tsx`
 - `server/src/routes/access.ts`
 - `server/src/lib/join-request-dedupe.ts`
@@ -23,16 +23,16 @@ This document maps the current invite creation and acceptance states implemented
 
 ```mermaid
 flowchart TD
-  Board[Board user on invite screen]
+  Board[Board user on invite or add-agent screen]
   HumanInvite[Create human company invite]
-  OpenClawInvite[Generate OpenClaw invite prompt]
+  AgentInvite[Generate agent onboarding 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]
+  HumanPending[Legacy human 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]
@@ -44,7 +44,7 @@ flowchart TD
   OpenClawReplay[Special replay path:<br/>accepted invite can be POSTed again<br/>for openclaw_gateway only]
 
   Board --> HumanInvite --> Active
-  Board --> OpenClawInvite --> Active
+  Board --> AgentInvite --> Active
   Active --> Revoked: revoke
   Active --> Expired: expiresAt passes
 
@@ -52,12 +52,10 @@ flowchart TD
   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
+  HumanReuse --> HumanApproved: reuse existing pending/approved request<br/>ensure active membership
+  HumanReuse --> HumanApproved: no reusable request<br/>create and approve request
+  HumanPending --> HumanApproved: same invitee replays accepted invite<br/>or board approves legacy request
   HumanPending --> HumanRejected: board rejects
-  HumanPending --> Accepted
   HumanApproved --> Accepted
 
   Active --> AgentPending: agent accept
@@ -102,10 +100,10 @@ stateDiagram-v2
     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
+  CompanySelection --> AgentPromptReady: Add-agent modal prompt generator
+  AgentPromptReady --> AgentPromptPending: Generate agent onboarding prompt
+  AgentPromptPending --> AgentSnippetVisible: prompt generated
+  AgentPromptPending --> AgentPromptReady: generation failed
 ```
 
 ## Invite Landing Screen States
@@ -150,7 +148,8 @@ stateDiagram-v2
 
   state AcceptedInviteSummary {
     [*] --> SummaryBranch
-    SummaryBranch --> PendingApprovalReload: joinRequestStatus=pending_approval
+    SummaryBranch --> AcceptPending: human joinRequestStatus=pending_approval/approved<br/>and membership missing
+    SummaryBranch --> PendingApprovalReload: agent 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
@@ -177,6 +176,7 @@ sequenceDiagram
   participant Landing as Invite landing UI
   participant Auth as Auth session
   participant Join as join_requests table
+  participant Membership as company_memberships + grants
 
   Board->>Settings: Choose role and click Create invite
   Settings->>API: POST /api/companies/:companyId/invites
@@ -197,15 +197,19 @@ sequenceDiagram
   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
+    API->>Membership: Ensure active membership and role grants
+    API->>Join: Mark join request approved if needed
+    API-->>Landing: approved join request
   else No reusable request exists
     API->>Invites: Mark invite accepted
     API->>Join: Insert pending_approval join request
-    API-->>Landing: New pending_approval join request
+    API->>Membership: Ensure active membership and role grants
+    API->>Join: Mark join request approved
+    API-->>Landing: approved join request
   end
 ```
 
-### Human Approval And Reload Path
+### Legacy Human Reload And Repair Path
 
 ```mermaid
 sequenceDiagram
@@ -214,8 +218,6 @@ sequenceDiagram
   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
@@ -223,20 +225,15 @@ sequenceDiagram
   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
+  alt human joinRequestStatus = pending_approval or approved but membership missing
+    Landing->>API: POST /api/invites/:token/accept (requestType=human)
+    API->>Membership: Ensure active membership and role grants
+    API->>Join: Mark join request approved if needed
     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
+  else agent invite or unavailable consumed state
     Landing-->>Invitee: Fall through to consumed/unavailable state
   end
 ```
@@ -247,21 +244,21 @@ sequenceDiagram
 sequenceDiagram
   autonumber
   actor Board as Board user
-  participant Settings as Company Settings UI
+  participant AddAgent as Add agent modal
   participant API as Access routes
   participant Invites as invites table
-  actor Gateway as OpenClaw gateway agent
+  actor Gateway as External 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
+  Board->>AddAgent: Generate agent onboarding prompt
+  AddAgent->>API: POST /api/companies/:companyId/invites (allowedJoinTypes=agent)
   API->>Invites: Insert active agent invite
-  API-->>Settings: Prompt text + invite token
+  API-->>AddAgent: Prompt text + invite token
 
-  Gateway->>API: POST /api/invites/:token/accept (agent, openclaw_gateway)
+  Gateway->>API: POST /api/invites/:token/accept (agent, adapter-specific payload)
   API->>Invites: Mark invite accepted
   API->>Join: Insert pending_approval join request + claimSecretHash
   API-->>Gateway: requestId + claimSecret + claimApiKeyPath
@@ -286,14 +283,15 @@ sequenceDiagram
 ## 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.
+- Human acceptance consumes the invite, creates or reuses the matching human join request, immediately marks it `approved`, and ensures an active company membership with the invite's selected role/grants.
 - 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
+  - human `pending_approval` or `approved` states replay acceptance for the same signed-in user/email so legacy consumed invites can repair missing membership
+  - agent `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
+  - `approved` becomes a success path for human invites after membership is visible to the current session
 - `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`.
+- Accepted-invite replay is supported for matching human invitees to repair/complete membership, and for `agent` requests with `adapterType=openclaw_gateway` when the existing join request is still `pending_approval` or already `approved`.
 - `bootstrap_ceo` invites are one-time and do not create join requests.

package.json

@@ -19,8 +19,8 @@
     "test": "pnpm run test:run",
     "test:watch": "pnpm run preflight:workspace-links && vitest",
     "test:run": "pnpm run preflight:workspace-links && node scripts/run-vitest-stable.mjs",
-    "test:run:general": "pnpm run preflight:workspace-links && pnpm --filter @paperclipai/plugin-sdk build && node scripts/run-vitest-stable.mjs --mode general",
-    "test:run:serialized": "pnpm run preflight:workspace-links && pnpm --filter @paperclipai/plugin-sdk build && node scripts/run-vitest-stable.mjs --mode serialized",
+    "test:run:general": "pnpm run preflight:workspace-links && pnpm --filter @paperclipai/plugin-sdk ensure-build-deps && node scripts/run-vitest-stable.mjs --mode general",
+    "test:run:serialized": "pnpm run preflight:workspace-links && pnpm --filter @paperclipai/plugin-sdk ensure-build-deps && node scripts/run-vitest-stable.mjs --mode serialized",
     "db:generate": "pnpm --filter @paperclipai/db generate",
     "db:migrate": "pnpm --filter @paperclipai/db migrate",
     "issue-references:backfill": "pnpm run preflight:workspace-links && tsx scripts/backfill-issue-reference-mentions.ts",

packages/adapter-utils/src/command-redaction.ts

@@ -1,20 +1,57 @@
 export const REDACTED_COMMAND_TEXT_VALUE = "***REDACTED***";
 
-const COMMAND_CLI_SECRET_OPTION_RE =
-  /(\B-{1,2}(?:api[-_]?key|(?:access[-_]?|auth[-_]?)?token|token|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)(?:\s+|=)(["']?))[^\s"'`]+(\2)/gi;
-const COMMAND_ENV_SECRET_ASSIGNMENT_RE =
-  /(\b[A-Za-z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD|PASSWD|AUTHORIZATION|JWT)[A-Za-z0-9_]*\s*=\s*)[^\s"'`]+/gi;
+const SECRET_NAME_PATTERN =
+  String.raw`[A-Za-z0-9_-]*(?:api[-_]?key|(?:access[-_]?|auth[-_]?)?token|token|authorization|bearer|secret|passwd|password|credential|jwt|private[-_]?key|cookie|connectionstring)[A-Za-z0-9_-]*`;
+
+const COMMAND_CLI_SECRET_OPTION_RE = new RegExp(
+  String.raw`(\B-{1,2}${SECRET_NAME_PATTERN}(?:\s+|=)(["']?))[^\s"'` + "`" + String.raw`]+(\2)`,
+  "gi",
+);
+const COMMAND_ENV_SECRET_ASSIGNMENT_RE = new RegExp(
+  String.raw`(\b${SECRET_NAME_PATTERN}\s*=\s*)(?:(["'])([^"'` + "`" + String.raw`\r\n]*)\2|([^\s"'` + "`" + String.raw`]+))`,
+  "gi",
+);
 const COMMAND_AUTHORIZATION_BEARER_RE = /(\bAuthorization\s*:\s*Bearer\s+)[^\s"'`]+/gi;
 const COMMAND_OPENAI_KEY_RE = /\bsk-[A-Za-z0-9_-]{12,}\b/g;
 const COMMAND_GITHUB_TOKEN_RE = /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g;
 const COMMAND_JWT_RE =
   /\b[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}(?:\.[A-Za-z0-9_-]{8,})?\b/g;
+const COMMAND_SECRET_HINTS = [
+  "api",
+  "key",
+  "token",
+  "auth",
+  "bearer",
+  "secret",
+  "pass",
+  "credential",
+  "jwt",
+  "private",
+  "cookie",
+  "connectionstring",
+  "sk-",
+  "ghp_",
+  "gho_",
+  "ghu_",
+  "ghs_",
+  "ghr_",
+] as const;
+
+function maybeContainsSecretText(command: string) {
+  const lower = command.toLowerCase();
+  return COMMAND_SECRET_HINTS.some((hint) => lower.includes(hint)) || command.includes(".");
+}
 
 export function redactCommandText(command: string, redactedValue = REDACTED_COMMAND_TEXT_VALUE): string {
+  if (!maybeContainsSecretText(command)) return command;
   return command
     .replace(COMMAND_AUTHORIZATION_BEARER_RE, `$1${redactedValue}`)
     .replace(COMMAND_CLI_SECRET_OPTION_RE, `$1${redactedValue}$3`)
-    .replace(COMMAND_ENV_SECRET_ASSIGNMENT_RE, `$1${redactedValue}`)
+    .replace(
+      COMMAND_ENV_SECRET_ASSIGNMENT_RE,
+      (_match, prefix: string, quote: string | undefined) =>
+        quote ? `${prefix}${quote}${redactedValue}${quote}` : `${prefix}${redactedValue}`,
+    )
     .replace(COMMAND_OPENAI_KEY_RE, redactedValue)
     .replace(COMMAND_GITHUB_TOKEN_RE, redactedValue)
     .replace(COMMAND_JWT_RE, redactedValue);

packages/adapter-utils/src/sandbox-managed-runtime.ts

@@ -138,6 +138,13 @@ async function createTarballFromDirectory(input: {
   const excludeArgs = ["._*", ...(input.exclude ?? [])].flatMap((entry) => ["--exclude", entry]);
   await execTar([
     "-c",
+    // Prevent macOS bsdtar from embedding LIBARCHIVE.xattr.* PAX extended
+    // headers for extended attributes (e.g. com.apple.provenance). GNU tar on
+    // Linux does not recognise these proprietary headers and fails extraction
+    // with "This does not look like a tar archive". COPYFILE_DISABLE=1 (set in
+    // execTar) already suppresses AppleDouble ._* sidecar files; --no-xattrs
+    // additionally suppresses the inline PAX xattr entries.
+    "--no-xattrs",
     ...(input.followSymlinks ? ["-h"] : []),
     "-f",
     input.archivePath,

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

@@ -53,13 +53,14 @@ describe("buildInvocationEnvForLogs", () => {
     const loggedEnv = buildInvocationEnvForLogs(
       { SAFE_VALUE: "visible" },
       {
-        resolvedCommand: "env OPENAI_API_KEY=sk-live-example custom-acp --token ghp_example_secret",
+        resolvedCommand:
+          "env OPENAI_API_KEY=sk-live-example PAPERCLIP_API_KEY='paperclip-quoted-secret' custom-acp --paperclip-api-key=paperclip-flag-secret --token ghp_example_secret",
       },
     );
 
     expect(loggedEnv.SAFE_VALUE).toBe("visible");
     expect(loggedEnv.PAPERCLIP_RESOLVED_COMMAND).toBe(
-      "env OPENAI_API_KEY=***REDACTED*** custom-acp --token ***REDACTED***",
+      "env OPENAI_API_KEY=***REDACTED*** PAPERCLIP_API_KEY='***REDACTED***' custom-acp --paperclip-api-key=***REDACTED*** --token ***REDACTED***",
     );
   });
 });
@@ -462,6 +463,50 @@ describe("renderPaperclipWakePrompt", () => {
     expect(prompt).toContain("named unblock owner/action");
   });
 
+  it("preserves Chinese, Japanese, and Hindi issue and comment text in scoped wake prompts", () => {
+    const title = "验证中文任务";
+    const commentBody = [
+      "请用中文回复。",
+      "日本語: 次の手順を書いてください。",
+      "हिन्दी: कृपया स्थिति बताएं।",
+    ].join("\n");
+    const payload = {
+      reason: "issue_commented",
+      issue: {
+        id: "issue-1",
+        identifier: "PAP-9452",
+        title,
+        status: "in_progress",
+        workMode: "standard",
+      },
+      commentIds: ["comment-1"],
+      latestCommentId: "comment-1",
+      commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },
+      comments: [
+        {
+          id: "comment-1",
+          body: commentBody,
+          author: { type: "user", id: "board-user-1" },
+          createdAt: "2026-05-15T16:30:00.000Z",
+        },
+      ],
+      fallbackFetchNeeded: false,
+    };
+
+    const serialized = stringifyPaperclipWakePayload(payload);
+    expect(serialized).toContain(title);
+    expect(serialized).toContain("日本語");
+    expect(serialized).toContain("हिन्दी");
+    expect(JSON.parse(serialized ?? "{}")).toMatchObject({
+      issue: { title },
+      comments: [{ body: commentBody }],
+    });
+
+    const prompt = renderPaperclipWakePrompt(payload);
+    expect(prompt).toContain(`- issue: PAP-9452 ${title}`);
+    expect(prompt).toContain(commentBody);
+  });
+
   it("renders planning-mode directives for assignment and comment wakes", () => {
     const assignmentPrompt = renderPaperclipWakePrompt({
       reason: "issue_assigned",

packages/adapters/acpx-local/src/server/execute.test.ts

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
+import type { AcpRuntimeOptions } from "acpx/runtime";
 import { createAcpxLocalExecutor } from "./execute.js";
 
 const tempRoots: string[] = [];
@@ -376,6 +377,126 @@ describe("acpx_local runtime skill isolation", () => {
     expect(envFiles.filter((contents) => contents.includes("PAPERCLIP_API_KEY='second-key'"))).toHaveLength(1);
   });
 
+  it("enriches acpx.error diagnostics and child stderr when ensureSession rejects", async () => {
+    const root = await makeTempRoot();
+    const stateDir = path.join(root, "state");
+    const runStderrDir = path.join(stateDir, "run-stderr");
+    await fs.mkdir(runStderrDir, { recursive: true });
+    const stderrTail = "claude-agent-acp: SDK init failed (auth missing)";
+    await fs.writeFile(path.join(runStderrDir, "run-1.log"), `${stderrTail}\n`, "utf8");
+
+    class FakeAcpRuntimeError extends Error {
+      readonly code = "ACP_SESSION_INIT_FAILED";
+      readonly cause: Error;
+      readonly retryable = false;
+      constructor(message: string, cause: Error) {
+        super(message);
+        this.name = "AcpRuntimeError";
+        this.cause = cause;
+      }
+    }
+
+    const logs: Array<{ stream: string; text: string }> = [];
+    const execute = createAcpxLocalExecutor({
+      createRuntime: () => ({
+        ensureSession: async () => {
+          throw new FakeAcpRuntimeError(
+            "session/new failed: backend rejected initialize",
+            new Error("upstream timeout"),
+          );
+        },
+        startTurn: () => ({
+          events: (async function* () {})(),
+          result: Promise.resolve({ status: "completed", stopReason: "end_turn" }),
+          cancel: async () => {},
+        }),
+        close: async () => {},
+      }) as never,
+    });
+
+    const result = await execute({
+      runId: "run-1",
+      agent: { id: "agent-1", companyId: "company-1" },
+      runtime: {},
+      config: {
+        agent: "custom",
+        agentCommand: "node ./fake-acp.js",
+        stateDir,
+      },
+      context: {},
+      onLog: async (stream: "stdout" | "stderr", text: string) => {
+        logs.push({ stream, text });
+      },
+      onMeta: async () => {},
+    } as never);
+
+    expect(result.exitCode).toBe(1);
+    expect(result.errorCode).toBe("acpx_session_init_failed");
+    const meta = result.errorMeta ?? {};
+    expect(meta.errorName).toBe("AcpRuntimeError");
+    expect(meta.acpCode).toBe("ACP_SESSION_INIT_FAILED");
+    expect(meta.causeMessage).toBe("upstream timeout");
+    expect(meta.retryable).toBe(false);
+    expect(typeof meta.stackPreview).toBe("string");
+    expect(meta.phase).toBe("ensure_session");
+
+    const errorLogLine = logs.find((entry) => entry.stream === "stdout" && entry.text.includes("\"type\":\"acpx.error\""));
+    expect(errorLogLine).toBeTruthy();
+    const errorPayload = JSON.parse(errorLogLine!.text.trim());
+    expect(errorPayload.phase).toBe("ensure_session");
+    expect(errorPayload.errorName).toBe("AcpRuntimeError");
+    expect(errorPayload.acpCode).toBe("ACP_SESSION_INIT_FAILED");
+    expect(errorPayload.causeMessage).toBe("upstream timeout");
+    expect(errorPayload.childStderrTail).toContain("SDK init failed");
+
+    const stderrLog = logs.find((entry) => entry.stream === "stderr" && entry.text.includes("ACPX child stderr tail"));
+    expect(stderrLog).toBeTruthy();
+    expect(stderrLog!.text).toContain(stderrTail);
+  });
+
+  it("writes wrapper that redirects child stderr to a per-run log file", async () => {
+    const root = await makeTempRoot();
+    const stateDir = path.join(root, "state");
+
+    const runtimeOptions: AcpRuntimeOptions[] = [];
+    const execute = createAcpxLocalExecutor({
+      createRuntime: (options) => {
+        runtimeOptions.push(options as unknown as AcpRuntimeOptions);
+        return buildRuntime() as never;
+      },
+    });
+
+    const result = await execute({
+      runId: "run-stderr-1",
+      agent: { id: "agent-1", companyId: "company-1" },
+      runtime: {},
+      config: {
+        agent: "custom",
+        agentCommand: "node ./fake-acp.js",
+        stateDir,
+      },
+      context: {},
+      onLog: async () => {},
+      onMeta: async () => {},
+    } as never);
+
+    expect(result.exitCode).toBe(0);
+    const verboseFlags = runtimeOptions.map((options) => (options as { verbose?: boolean }).verbose);
+    // verbose is scoped to the claude agent (PAPA-388); the custom agent here
+    // should not opt in to ACPX runtime verbose session-event logs.
+    expect(verboseFlags.every((flag) => flag === false)).toBe(true);
+
+    const wrappers = await fs.readdir(path.join(stateDir, "wrappers"));
+    const wrapperFile = wrappers.find((name) => name.endsWith(".sh"));
+    expect(wrapperFile).toBeTruthy();
+    const wrapper = await fs.readFile(path.join(stateDir, "wrappers", wrapperFile!), "utf8");
+    expect(wrapper).toContain("stderr_dir=");
+    expect(wrapper).toContain("run-stderr");
+    expect(wrapper).toContain("PAPERCLIP_RUN_ID");
+    expect(wrapper).toContain("tee -a");
+    expect(wrapper).toContain("exec node ./fake-acp.js");
+  });
+
   it("passes Paperclip env through the ACP agent wrapper instead of process.env", async () => {
     let observedApiKeyDuringStream: string | undefined;
     const execute = createAcpxLocalExecutor({
@@ -422,4 +543,160 @@ describe("acpx_local runtime skill isolation", () => {
       else process.env.PAPERCLIP_API_KEY = previousApiKey;
     }
   });
+
+  it("writes a Paperclip-managed .claude/settings.local.json for the claude agent so it can reach the Paperclip API", async () => {
+    const root = await makeTempRoot();
+    const stateDir = path.join(root, "state");
+    const cwd = path.join(root, "worktree");
+    await fs.mkdir(cwd, { recursive: true });
+
+    const { meta } = await runExecutor(
+      { agent: "claude", stateDir, cwd },
+      { context: { paperclipWorkspace: { cwd, agentHome: path.join(root, "agent-home") } } },
+    );
+
+    const settingsPath = path.join(cwd, ".claude", "settings.local.json");
+    const written = JSON.parse(await fs.readFile(settingsPath, "utf8")) as {
+      permissions?: {
+        allow?: unknown;
+        additionalDirectories?: unknown;
+        defaultMode?: unknown;
+      };
+    };
+    expect(written.permissions?.defaultMode).toBe("default");
+    const allow = written.permissions?.allow;
+    expect(Array.isArray(allow)).toBe(true);
+    expect(allow).toContain("Bash(curl:*)");
+    expect(allow).toContain(`Bash(${cwd}/scripts/paperclip-issue-update.sh:*)`);
+    const additionalDirectories = written.permissions?.additionalDirectories as string[] | undefined;
+    expect(Array.isArray(additionalDirectories)).toBe(true);
+    expect(additionalDirectories).toContain(stateDir);
+    expect(additionalDirectories).toContain(path.join(root, "agent-home"));
+
+    const note = (meta[0]?.commandNotes as string[] | undefined)?.find((entry) =>
+      entry.includes("Paperclip-managed Claude settings"),
+    );
+    expect(note).toBeTruthy();
+  });
+
+  it("merges Paperclip allowlist into an existing .claude/settings.local.json without losing user entries", async () => {
+    const root = await makeTempRoot();
+    const stateDir = path.join(root, "state");
+    const cwd = path.join(root, "worktree");
+    await fs.mkdir(path.join(cwd, ".claude"), { recursive: true });
+    await fs.writeFile(
+      path.join(cwd, ".claude", "settings.local.json"),
+      JSON.stringify(
+        {
+          statusLine: { type: "command", command: "preserve-me" },
+          permissions: {
+            allow: ["Bash(npm test:*)"],
+            additionalDirectories: ["/Users/example/custom"],
+            defaultMode: "acceptEdits",
+          },
+        },
+        null,
+        2,
+      ),
+      "utf8",
+    );
+
+    await runExecutor(
+      { agent: "claude", stateDir, cwd },
+      { context: { paperclipWorkspace: { cwd } } },
+    );
+
+    const written = JSON.parse(
+      await fs.readFile(path.join(cwd, ".claude", "settings.local.json"), "utf8"),
+    ) as {
+      statusLine?: unknown;
+      permissions?: {
+        allow?: string[];
+        additionalDirectories?: string[];
+        defaultMode?: string;
+      };
+    };
+    expect(written.statusLine).toEqual({ type: "command", command: "preserve-me" });
+    expect(written.permissions?.defaultMode).toBe("acceptEdits");
+    expect(written.permissions?.allow).toContain("Bash(npm test:*)");
+    expect(written.permissions?.allow).toContain("Bash(curl:*)");
+    expect(written.permissions?.additionalDirectories).toContain("/Users/example/custom");
+    expect(written.permissions?.additionalDirectories).toContain(stateDir);
+  });
+
+  it("overrides a user-supplied dontAsk defaultMode so ACPX can route Bash through canUseTool", async () => {
+    const root = await makeTempRoot();
+    const stateDir = path.join(root, "state");
+    const cwd = path.join(root, "worktree");
+    await fs.mkdir(path.join(cwd, ".claude"), { recursive: true });
+    await fs.writeFile(
+      path.join(cwd, ".claude", "settings.local.json"),
+      JSON.stringify({ permissions: { defaultMode: "dontAsk" } }, null, 2),
+      "utf8",
+    );
+
+    const { meta } = await runExecutor(
+      { agent: "claude", stateDir, cwd },
+      { context: { paperclipWorkspace: { cwd } } },
+    );
+
+    const written = JSON.parse(
+      await fs.readFile(path.join(cwd, ".claude", "settings.local.json"), "utf8"),
+    ) as { permissions?: { defaultMode?: string } };
+    expect(written.permissions?.defaultMode).toBe("default");
+
+    const overrideNote = (meta[0]?.commandNotes as string[] | undefined)?.find((entry) =>
+      entry.includes("overrode user dontAsk"),
+    );
+    expect(overrideNote).toBeTruthy();
+  });
+
+  it("opts the claude agent into ACPX runtime verbose logs but leaves codex/custom agents quiet", async () => {
+    const root = await makeTempRoot();
+    const cwd = path.join(root, "worktree");
+    await fs.mkdir(cwd, { recursive: true });
+
+    const verboseByAgent: Record<string, boolean | undefined> = {};
+    for (const agent of ["claude", "codex", "custom"] as const) {
+      const runtimeOptions: AcpRuntimeOptions[] = [];
+      const execute = createAcpxLocalExecutor({
+        createRuntime: (options) => {
+          runtimeOptions.push(options as AcpRuntimeOptions);
+          return buildRuntime() as never;
+        },
+      });
+      const result = await execute({
+        runId: `run-${agent}`,
+        agent: { id: `agent-${agent}`, companyId: "company-1" },
+        runtime: {},
+        config:
+          agent === "custom"
+            ? { agent, agentCommand: "node ./fake-acp.js", stateDir: path.join(root, `state-${agent}`), cwd }
+            : { agent, stateDir: path.join(root, `state-${agent}`), cwd },
+        context: { paperclipWorkspace: { cwd } },
+        onLog: async () => {},
+        onMeta: async () => {},
+      } as never);
+      expect(result.exitCode).toBe(0);
+      verboseByAgent[agent] = (runtimeOptions[0] as { verbose?: boolean } | undefined)?.verbose;
+    }
+
+    expect(verboseByAgent.claude).toBe(true);
+    expect(verboseByAgent.codex).toBe(false);
+    expect(verboseByAgent.custom).toBe(false);
+  });
+
+  it("does not touch .claude/settings.local.json for the codex agent", async () => {
+    const root = await makeTempRoot();
+    const stateDir = path.join(root, "state");
+    const cwd = path.join(root, "worktree");
+    await fs.mkdir(cwd, { recursive: true });
+
+    await runExecutor(
+      { agent: "codex", stateDir, cwd },
+      { context: { paperclipWorkspace: { cwd } } },
+    );
+
+    expect(await pathExists(path.join(cwd, ".claude", "settings.local.json"))).toBe(false);
+  });
 });

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

@@ -94,6 +94,8 @@ interface AcpxPreparedRuntime {
   remoteExecutionIdentity: Record<string, unknown> | null;
   skillPromptInstructions: string;
   skillsIdentity: Record<string, unknown>;
+  childStderrLogPath: string | null;
+  paperclipClaudeSettings: PaperclipClaudeSettingsResult | null;
 }
 
 const defaultWarmHandles = new Map<string, RuntimeCacheEntry>();
@@ -564,11 +566,105 @@ function buildSessionParams(input: {
   };
 }
 
+interface PaperclipClaudeSettingsResult {
+  filePath: string;
+  allow: string[];
+  additionalDirectories: string[];
+  defaultMode: string;
+  overrodeDontAsk: boolean;
+}
+
+function uniqueSorted(values: Array<string | null | undefined>): string[] {
+  return [...new Set(values.filter((value): value is string => typeof value === "string" && value.length > 0))].sort();
+}
+
+// Phase 4.1 (PAPA-388): the Claude Code SDK that `claude-agent-acp` runs uses
+// `settingSources: ["user", "project", "local"]`. By writing a per-worktree
+// `.claude/settings.local.json` we override the user's potentially-restrictive
+// `~/.claude/settings.json` (e.g. `defaultMode: "dontAsk"`, which silently
+// denies every non-allowlisted tool and never reaches `canUseTool`), and we
+// widen the SDK's Read sandbox to include the Paperclip state dirs the agent
+// needs to talk to its own control plane.
+async function writePaperclipClaudeSettings(input: {
+  cwd: string;
+  stateDir: string;
+  agentHome: string;
+  companyId: string;
+}): Promise<PaperclipClaudeSettingsResult> {
+  const filePath = path.join(input.cwd, ".claude", "settings.local.json");
+  const instanceRoot = defaultPaperclipInstanceDir();
+  const companyRoot = path.join(instanceRoot, "companies", input.companyId);
+  const paperclipAdditionalDirectories = uniqueSorted([
+    input.stateDir,
+    input.agentHome,
+    companyRoot,
+  ]);
+  const paperclipAllow = uniqueSorted([
+    "Bash(curl:*)",
+    "Bash(env:*)",
+    "Bash(env)",
+    `Bash(${input.cwd}/scripts/paperclip-issue-update.sh:*)`,
+    `Bash(${input.cwd}/scripts/paperclip:*)`,
+  ]);
+
+  let existing: Record<string, unknown> = {};
+  const existingRaw = await fs.readFile(filePath, "utf8").catch(() => null);
+  if (existingRaw) {
+    try {
+      const parsed = JSON.parse(existingRaw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) existing = parsed as Record<string, unknown>;
+    } catch {
+      // Malformed settings file — leave it alone in `existing` and our merge will replace it with a valid one.
+    }
+  }
+  const existingPerms =
+    existing.permissions && typeof existing.permissions === "object" && !Array.isArray(existing.permissions)
+      ? (existing.permissions as Record<string, unknown>)
+      : {};
+  const existingAllow = Array.isArray(existingPerms.allow)
+    ? (existingPerms.allow as unknown[]).filter((value): value is string => typeof value === "string")
+    : [];
+  const existingAdditionalDirectories = Array.isArray(existingPerms.additionalDirectories)
+    ? (existingPerms.additionalDirectories as unknown[]).filter((value): value is string => typeof value === "string")
+    : [];
+  const mergedAllow = uniqueSorted([...existingAllow, ...paperclipAllow]);
+  const mergedAdditionalDirectories = uniqueSorted([
+    ...existingAdditionalDirectories,
+    ...paperclipAdditionalDirectories,
+  ]);
+  const existingDefaultMode =
+    typeof existingPerms.defaultMode === "string" ? (existingPerms.defaultMode as string) : "";
+  const defaultMode =
+    existingDefaultMode && existingDefaultMode !== "dontAsk" ? existingDefaultMode : "default";
+  const overrodeDontAsk = existingDefaultMode === "dontAsk";
+
+  const nextPermissions: Record<string, unknown> = {
+    ...existingPerms,
+    allow: mergedAllow,
+    additionalDirectories: mergedAdditionalDirectories,
+    defaultMode,
+  };
+  const next: Record<string, unknown> = { ...existing, permissions: nextPermissions };
+  await writeFileAtomically({
+    target: filePath,
+    contents: `${JSON.stringify(next, null, 2)}\n`,
+    mode: 0o600,
+  });
+  return {
+    filePath,
+    allow: mergedAllow,
+    additionalDirectories: mergedAdditionalDirectories,
+    defaultMode,
+    overrodeDontAsk,
+  };
+}
+
 async function writeAgentWrapper(input: {
   stateDir: string;
   acpxAgent: string;
   agentCommandShell: string;
   env: Record<string, string>;
+  childStderrDir: string;
 }): Promise<{ wrapperPath: string; envFilePath: string }> {
   const wrappersDir = path.join(input.stateDir, "wrappers");
   await fs.mkdir(wrappersDir, { recursive: true });
@@ -580,6 +676,7 @@ async function writeAgentWrapper(input: {
     agent: input.acpxAgent,
     command: input.agentCommandShell,
     env: envLines,
+    childStderrDir: input.childStderrDir,
   });
   const wrapperPath = path.join(wrappersDir, `${input.acpxAgent}-${wrapperHash}.sh`);
   const envFilePath = path.join(wrappersDir, `${input.acpxAgent}-${wrapperHash}.env`);
@@ -592,6 +689,11 @@ async function writeAgentWrapper(input: {
     "  source \"$env_file\"",
     "  set +a",
     "fi",
+    `stderr_dir=${shellQuote(input.childStderrDir)}`,
+    "if [[ -n \"${PAPERCLIP_RUN_ID:-}\" ]]; then",
+    "  mkdir -p \"$stderr_dir\"",
+    "  exec 2> >(tee -a \"$stderr_dir/$PAPERCLIP_RUN_ID.log\" >&2)",
+    "fi",
     `exec ${input.agentCommandShell} "$@"`,
     "",
   ].join("\n");
@@ -723,10 +825,20 @@ async function buildRuntime(input: {
     if (typeof value === "string") env[key] = value;
   }
   if (!hasExplicitApiKey && authToken) env.PAPERCLIP_API_KEY = authToken;
+  // For the claude agent, set model via ANTHROPIC_MODEL at startup rather than
+  // via session/set_config_option — the ACP server's set_config_option handler
+  // validates the value against its internal available-models list and rejects
+  // bare model IDs (e.g. "claude-opus-4-7") that don't exactly match a model
+  // entry in some versions. ANTHROPIC_MODEL is read during initialization, so
+  // it reliably sets the model before any turns are run.
+  if (requestedModel && acpxAgent === "claude" && !env.ANTHROPIC_MODEL) {
+    env.ANTHROPIC_MODEL = requestedModel;
+  }
 
   let skillPromptInstructions = "";
   let skillsIdentity: Record<string, unknown> = { mode: "unsupported" };
   const skillCommandNotes: string[] = [];
+  let paperclipClaudeSettings: PaperclipClaudeSettingsResult | null = null;
   if (acpxAgent === "claude") {
     const preparedSkills = await prepareClaudeSkillRuntime({
       stateDir,
@@ -736,6 +848,17 @@ async function buildRuntime(input: {
     skillPromptInstructions = preparedSkills.promptInstructions;
     skillsIdentity = preparedSkills.identity;
     skillCommandNotes.push(...preparedSkills.commandNotes);
+    paperclipClaudeSettings = await writePaperclipClaudeSettings({
+      cwd,
+      stateDir,
+      agentHome,
+      companyId: agent.companyId,
+    });
+    skillCommandNotes.push(
+      `Wrote Paperclip-managed Claude settings to ${paperclipClaudeSettings.filePath} (defaultMode=${paperclipClaudeSettings.defaultMode}${
+        paperclipClaudeSettings.overrodeDontAsk ? "; overrode user dontAsk" : ""
+      }, +${paperclipClaudeSettings.additionalDirectories.length} read root(s), +${paperclipClaudeSettings.allow.length} allow rule(s)).`,
+    );
   } else if (acpxAgent === "codex") {
     const preparedSkills = await prepareCodexSkillRuntime({
       companyId: agent.companyId,
@@ -757,12 +880,15 @@ async function buildRuntime(input: {
   const builtInCommand = resolveBuiltInAgentCommand(acpxAgent);
   const agentCommand = configuredCommand || builtInCommand || null;
   const agentCommandShell = configuredCommand || (builtInCommand ? shellQuote(builtInCommand) : "");
+  const childStderrDir = path.join(stateDir, "run-stderr");
+  const childStderrLogPath = agentCommand ? path.join(childStderrDir, `${runId}.log`) : null;
   const wrapper = agentCommand
     ? await writeAgentWrapper({
         stateDir,
         acpxAgent,
         agentCommandShell,
         env,
+        childStderrDir,
       })
     : null;
   const wrapperPath = wrapper?.wrapperPath ?? null;
@@ -781,6 +907,13 @@ async function buildRuntime(input: {
     remoteExecutionIdentity,
     skillsIdentity,
     skillPromptInstructions,
+    paperclipClaudeSettings: paperclipClaudeSettings
+      ? {
+          allow: paperclipClaudeSettings.allow,
+          additionalDirectories: paperclipClaudeSettings.additionalDirectories,
+          defaultMode: paperclipClaudeSettings.defaultMode,
+        }
+      : null,
   });
   const taskKey = asString(input.ctx.runtime.taskKey, "") || wakeTaskId || workspaceId || "default";
   const sessionKey = `paperclip:${agent.companyId}:${agent.id}:${taskKey}:${fingerprint}`;
@@ -817,12 +950,19 @@ async function buildRuntime(input: {
       ...skillsIdentity,
       commandNotes: skillCommandNotes,
     },
+    childStderrLogPath,
+    paperclipClaudeSettings,
   };
 }
 
 function sessionConfigOptions(prepared: AcpxPreparedRuntime): Array<{ key: string; value: string }> {
   const options: Array<{ key: string; value: string }> = [];
-  if (prepared.requestedModel) options.push({ key: "model", value: prepared.requestedModel });
+  // Model for the claude agent is pre-set via ANTHROPIC_MODEL env var at
+  // startup; skip set_config_option to avoid ACP-server model-name validation
+  // that rejects bare IDs like "claude-opus-4-7" in some runtime versions.
+  if (prepared.requestedModel && prepared.acpxAgent !== "claude") {
+    options.push({ key: "model", value: prepared.requestedModel });
+  }
   if (prepared.requestedThinkingEffort) {
     options.push({
       key: prepared.acpxAgent === "codex" ? "reasoning_effort" : "effort",
@@ -999,33 +1139,151 @@ function resultErrorMessage(result: AcpRuntimeTurnResult): string | null {
   return result.error.message;
 }
 
-function classifyError(err: unknown): Pick<AdapterExecutionResult, "errorCode" | "errorMeta"> {
-  const message = err instanceof Error ? err.message : String(err);
+type AcpxExecutionPhase = "ensure_session" | "configure_session" | "turn";
+
+function describeErrorDiagnostics(err: unknown): {
+  errorName: string;
+  acpCode: string | null;
+  causeMessage: string | null;
+  retryable: boolean | null;
+  stackPreview: string | null;
+} {
+  const errorName =
+    err instanceof Error ? err.name || err.constructor.name : typeof err;
   const maybeCode =
     err && typeof err === "object" && typeof (err as { code?: unknown }).code === "string"
       ? (err as { code: string }).code
       : null;
-  const acpCode = isAcpRuntimeError(err) || (maybeCode?.startsWith("ACP_") ?? false) ? maybeCode : null;
+  const acpCode =
+    isAcpRuntimeError(err) || (maybeCode?.startsWith("ACP_") ?? false) ? maybeCode : null;
+  const cause =
+    err && typeof err === "object" && (err as { cause?: unknown }).cause !== undefined
+      ? (err as { cause?: unknown }).cause
+      : undefined;
+  const causeMessage =
+    cause instanceof Error
+      ? cause.message
+      : typeof cause === "string"
+        ? cause
+        : null;
+  const retryable =
+    err && typeof err === "object" && typeof (err as { retryable?: unknown }).retryable === "boolean"
+      ? (err as { retryable: boolean }).retryable
+      : null;
+  const stack = err instanceof Error && typeof err.stack === "string" ? err.stack : "";
+  const stackPreview = stack ? stack.split("\n").slice(0, 6).join("\n") : null;
+  return { errorName, acpCode, causeMessage, retryable, stackPreview };
+}
+
+function classifyError(
+  err: unknown,
+  phase?: AcpxExecutionPhase,
+): Pick<AdapterExecutionResult, "errorCode" | "errorMeta"> {
+  const message = err instanceof Error ? err.message : String(err);
+  const diagnostics = describeErrorDiagnostics(err);
+  const { acpCode, errorName, causeMessage, retryable, stackPreview } = diagnostics;
+  const baseMeta: Record<string, unknown> = {
+    errorName,
+    ...(acpCode ? { acpCode } : {}),
+    ...(causeMessage ? { causeMessage } : {}),
+    ...(retryable !== null ? { retryable } : {}),
+    ...(stackPreview ? { stackPreview } : {}),
+    ...(phase ? { phase } : {}),
+  };
   const lower = message.toLowerCase();
   const authLike = lower.includes("auth") || lower.includes("login") || lower.includes("credential");
   if (authLike) {
     return {
       errorCode: "acpx_auth_required",
-      errorMeta: { category: "auth", ...(acpCode ? { acpCode } : {}) },
+      errorMeta: { category: "auth", ...baseMeta },
+    };
+  }
+  const phaseCode = (() => {
+    if (acpCode === "ACP_SESSION_INIT_FAILED") return "acpx_session_init_failed";
+    if (acpCode === "ACP_TURN_FAILED") return "acpx_turn_failed";
+    if (acpCode === "ACP_BACKEND_MISSING") return "acpx_backend_missing";
+    if (acpCode === "ACP_BACKEND_UNAVAILABLE") return "acpx_backend_unavailable";
+    if (phase === "ensure_session") return "acpx_session_init_failed";
+    if (phase === "configure_session") return "acpx_session_config_failed";
+    if (phase === "turn") return "acpx_turn_failed";
+    return null;
+  })();
+  if (phaseCode) {
+    return {
+      errorCode: phaseCode,
+      errorMeta: { category: acpCode ? "protocol" : "runtime", ...baseMeta },
     };
   }
   if (acpCode) {
     return {
       errorCode: "acpx_protocol_error",
-      errorMeta: { category: "protocol", acpCode },
+      errorMeta: { category: "protocol", ...baseMeta },
     };
   }
   return {
     errorCode: "acpx_runtime_error",
-    errorMeta: { category: "runtime" },
+    errorMeta: { category: "runtime", ...baseMeta },
   };
 }
 
+async function readChildStderrTail(input: {
+  logPath: string | null;
+  maxBytes?: number;
+}): Promise<string | null> {
+  if (!input.logPath) return null;
+  const maxBytes = input.maxBytes ?? 4096;
+  let handle: fs.FileHandle | null = null;
+  try {
+    const stat = await fs.stat(input.logPath);
+    if (stat.size === 0) return null;
+    handle = await fs.open(input.logPath, "r");
+    const readBytes = Math.min(stat.size, maxBytes);
+    const buffer = Buffer.alloc(readBytes);
+    await handle.read(buffer, 0, readBytes, Math.max(0, stat.size - readBytes));
+    const tail = buffer.toString("utf8").trim();
+    return tail.length > 0 ? tail : null;
+  } catch {
+    return null;
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+  }
+}
+
+async function emitAcpxFailure(input: {
+  ctx: AdapterExecutionContext;
+  prepared: AcpxPreparedRuntime;
+  err: unknown;
+  phase: AcpxExecutionPhase;
+  // Replace the err-derived message in both the stderr-tail log header and the
+  // acpx.error payload. Used by the turn path to surface "Timed out after Ns"
+  // instead of the raw underlying error message.
+  messageOverride?: string;
+}): Promise<{
+  classified: Pick<AdapterExecutionResult, "errorCode" | "errorMeta">;
+  message: string;
+  childStderrTail: string | null;
+}> {
+  const { ctx, prepared, err, phase, messageOverride } = input;
+  const rawMessage = err instanceof Error ? err.message : String(err);
+  const message = messageOverride ?? rawMessage;
+  const classified = classifyError(err, phase);
+  const childStderrTail = await readChildStderrTail({ logPath: prepared.childStderrLogPath });
+  if (childStderrTail) {
+    await ctx.onLog(
+      "stderr",
+      `[paperclip] ACPX child stderr tail (${phase}):\n${childStderrTail}\n`,
+    );
+  }
+  await emitAcpxLog(ctx, {
+    type: "acpx.error",
+    message,
+    phase,
+    ...classified.errorMeta,
+    ...(childStderrTail ? { childStderrTail } : {}),
+  });
+  return { classified, message, childStderrTail };
+}
+
 function isResumeFailure(err: unknown): boolean {
   const message = err instanceof Error ? err.message : String(err);
   return /resume|load|not found|no session|unknown session|conversation/i.test(message);
@@ -1136,6 +1394,11 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
       permissionMode: prepared.permissionMode,
       nonInteractivePermissions: prepared.nonInteractivePermissions,
       timeoutMs: prepared.timeoutSec > 0 ? prepared.timeoutSec * 1000 : undefined,
+      // Scope ACPX runtime verbose logs to the claude agent only — that's the
+      // surface we know needs the extra session-event detail (PAPA-388). codex
+      // and custom agents already emit their own per-tool output and don't
+      // benefit from doubling the log volume.
+      verbose: prepared.acpxAgent === "claude",
     };
     const runtime = cached?.runtime ?? createRuntime(runtimeOptions);
     if (cached) clearWarmHandleTimer(cached);
@@ -1177,9 +1440,12 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         }
       }
     } catch (err) {
-      const classified = classifyError(err);
-      const message = err instanceof Error ? err.message : String(err);
-      await emitAcpxLog(ctx, { type: "acpx.error", message, ...classified.errorMeta });
+      const { classified, message } = await emitAcpxFailure({
+        ctx,
+        prepared,
+        err,
+        phase: "ensure_session",
+      });
       return {
         exitCode: 1,
         signal: null,
@@ -1216,9 +1482,12 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         onLog: ctx.onLog,
       });
     } catch (err) {
-      const classified = classifyError(err);
-      const message = err instanceof Error ? err.message : String(err);
-      await emitAcpxLog(ctx, { type: "acpx.error", message, ...classified.errorMeta });
+      const { classified, message } = await emitAcpxFailure({
+        ctx,
+        prepared,
+        err,
+        phase: "configure_session",
+      });
       await runtime.close({
         handle: sessionHandle,
         reason: "paperclip config cleanup",
@@ -1271,7 +1540,13 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         commandNotes: [
           `ACPX runtime embedded in Paperclip with ${prepared.mode} session mode.`,
           `Effective ACPX permission mode: ${prepared.permissionMode}.`,
-          ...(prepared.requestedModel ? [`Requested ACPX model: ${prepared.requestedModel}.`] : []),
+          ...(prepared.requestedModel
+            ? [
+                prepared.acpxAgent === "claude"
+                  ? `Requested ACPX model: ${prepared.requestedModel} (set via ANTHROPIC_MODEL env at startup).`
+                  : `Requested ACPX model: ${prepared.requestedModel}.`,
+              ]
+            : []),
           ...(prepared.requestedThinkingEffort ? [`Requested ACPX thinking effort: ${prepared.requestedThinkingEffort}.`] : []),
           ...(prepared.fastMode ? ["Requested ACPX Codex fast mode."] : []),
           ...(Array.isArray(prepared.skillsIdentity.commandNotes)
@@ -1414,10 +1689,11 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
       };
     } catch (err) {
       if (timeout) clearTimeout(timeout);
-      const classified = classifyError(err);
-      const message = timedOut ? `Timed out after ${prepared.timeoutSec}s` : err instanceof Error ? err.message : String(err);
+      const messageOverride = timedOut ? `Timed out after ${prepared.timeoutSec}s` : undefined;
       const cancel = cancelActiveTurn as ((reason: string) => Promise<void>) | null;
-      if (cancel) await cancel(message).catch(() => {});
+      const preEmitMessage =
+        messageOverride ?? (err instanceof Error ? err.message : String(err));
+      if (cancel) await cancel(preEmitMessage).catch(() => {});
       await runtime.close({
         handle: sessionHandle,
         reason: timedOut ? "paperclip timeout cleanup" : "paperclip error cleanup",
@@ -1428,7 +1704,13 @@ export function createAcpxLocalExecutor(deps: ExecuteDeps = {}) {
         clearWarmHandleTimer(existing);
         warmHandles.delete(prepared.sessionKey);
       }
-      await emitAcpxLog(ctx, { type: "acpx.error", message, ...classified.errorMeta });
+      const { classified, message } = await emitAcpxFailure({
+        ctx,
+        prepared,
+        err,
+        phase: "turn",
+        messageOverride,
+      });
       return {
         exitCode: 1,
         signal: timedOut ? "SIGTERM" : null,

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

@@ -212,6 +212,14 @@ export async function testEnvironment(
       if (maxTurns > 0) args.push("--max-turns", String(maxTurns));
       if (extraArgs.length > 0) args.push(...extraArgs);
 
+      // Sandbox bridges still add lease warmup and transport overhead, but
+      // the standard-2 Cloudflare tier now probes fast enough that a 90s
+      // budget leaves headroom without masking real hangs.
+      const helloProbeTimeoutSec = Math.max(
+        1,
+        asNumber(config.helloProbeTimeoutSec, targetIsSandbox ? 90 : 45),
+      );
+
       const probe = await runAdapterExecutionTargetProcess(
         runId,
         target,
@@ -220,7 +228,7 @@ export async function testEnvironment(
         {
           cwd,
           env,
-          timeoutSec: 45,
+          timeoutSec: helloProbeTimeoutSec,
           graceSec: 5,
           stdin: "Respond with hello.",
           onLog: async () => {},

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

@@ -52,7 +52,8 @@ export const modelProfiles: AdapterModelProfileDefinition[] = [
     description: "Use the lowest-cost known Codex local model lane without changing the primary model.",
     adapterConfig: {
       model: "gpt-5.3-codex-spark",
-      modelReasoningEffort: "low",
+      // Spark is the cheap lane by model price; high effort keeps Codex coding behavior usable for delegated work.
+      modelReasoningEffort: "high",
     },
     source: "adapter_default",
   },

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

@@ -0,0 +1,57 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { prepareManagedCodexHome } from "./codex-home.js";
+
+describe("codex managed home", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("treats a concurrently-created expected auth symlink as success", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-codex-home-"));
+    const sharedCodexHome = path.join(root, "shared-codex-home");
+    const paperclipHome = path.join(root, "paperclip-home");
+    const managedCodexHome = path.join(
+      paperclipHome,
+      "instances",
+      "default",
+      "companies",
+      "company-1",
+      "codex-home",
+    );
+    const sharedAuth = path.join(sharedCodexHome, "auth.json");
+    const managedAuth = path.join(managedCodexHome, "auth.json");
+
+    await fs.mkdir(sharedCodexHome, { recursive: true });
+    await fs.writeFile(sharedAuth, '{"token":"shared"}\n', "utf8");
+
+    const originalSymlink = fs.symlink.bind(fs);
+    vi.spyOn(fs, "symlink").mockImplementationOnce(async (source, target, type) => {
+      await originalSymlink(source, target, type);
+      const error = new Error("file already exists") as NodeJS.ErrnoException;
+      error.code = "EEXIST";
+      throw error;
+    });
+
+    try {
+      await expect(
+        prepareManagedCodexHome(
+          {
+            CODEX_HOME: sharedCodexHome,
+            PAPERCLIP_HOME: paperclipHome,
+            PAPERCLIP_INSTANCE_ID: "default",
+          },
+          async () => {},
+          "company-1",
+        ),
+      ).resolves.toBe(managedCodexHome);
+
+      expect((await fs.lstat(managedAuth)).isSymbolicLink()).toBe(true);
+      expect(await fs.realpath(managedAuth)).toBe(await fs.realpath(sharedAuth));
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -45,11 +45,31 @@ async function ensureParentDir(target: string): Promise<void> {
   await fs.mkdir(path.dirname(target), { recursive: true });
 }
 
+async function isExpectedSymlink(target: string, source: string): Promise<boolean> {
+  const existing = await fs.lstat(target).catch(() => null);
+  if (!existing?.isSymbolicLink()) return false;
+
+  const linkedPath = await fs.readlink(target).catch(() => null);
+  if (!linkedPath) return false;
+
+  return path.resolve(path.dirname(target), linkedPath) === path.resolve(source);
+}
+
+async function createExpectedSymlink(target: string, source: string): Promise<void> {
+  try {
+    await fs.symlink(source, target);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "EEXIST" && await isExpectedSymlink(target, source)) return;
+    throw error;
+  }
+}
+
 async function ensureSymlink(target: string, source: string): Promise<void> {
   const existing = await fs.lstat(target).catch(() => null);
   if (!existing) {
     await ensureParentDir(target);
-    await fs.symlink(source, target);
+    await createExpectedSymlink(target, source);
     return;
   }
 
@@ -57,14 +77,10 @@ async function ensureSymlink(target: string, source: string): Promise<void> {
     return;
   }
 
-  const linkedPath = await fs.readlink(target).catch(() => null);
-  if (!linkedPath) return;
-
-  const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
-  if (resolvedLinkedPath === source) return;
+  if (await isExpectedSymlink(target, source)) return;
 
   await fs.unlink(target);
-  await fs.symlink(source, target);
+  await createExpectedSymlink(target, source);
 }
 
 async function ensureCopiedFile(target: string, source: string): Promise<void> {

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

@@ -4,6 +4,7 @@ import type {
   AdapterEnvironmentTestResult,
 } from "@paperclipai/adapter-utils";
 import {
+  asNumber,
   asString,
   asStringArray,
   parseObject,
@@ -98,6 +99,7 @@ export async function testEnvironment(
   let command = asString(config.command, "agent");
   const target = ctx.executionTarget ?? null;
   const targetIsRemote = target?.kind === "remote";
+  const targetIsSandbox = target?.kind === "remote" && target.transport === "sandbox";
   const cwd = resolveAdapterExecutionTargetCwd(target, asString(config.cwd, ""), process.cwd());
   const targetLabel = targetIsRemote
     ? ctx.environmentName ?? describeAdapterExecutionTarget(target)
@@ -230,6 +232,12 @@ export async function testEnvironment(
         hint: "Use `agent` or `cursor-agent` to run the automatic installation and auth probe.",
       });
     } else {
+      // Cursor's `agent` binary still pays cold-start overhead in container
+      // sandboxes, but standard-2 probes no longer need a 120s version budget.
+      const versionProbeTimeoutSec = Math.max(
+        1,
+        asNumber(config.versionProbeTimeoutSec, targetIsSandbox ? 60 : 45),
+      );
       const versionProbe = await runAdapterExecutionTargetProcess(
         runId,
         target,
@@ -238,7 +246,7 @@ export async function testEnvironment(
         {
           cwd,
           env,
-          timeoutSec: 45,
+          timeoutSec: versionProbeTimeoutSec,
           graceSec: 5,
           onLog: async () => {},
         },
@@ -295,6 +303,12 @@ export async function testEnvironment(
       if (extraArgs.length > 0) args.push(...extraArgs);
       args.push("Respond with hello.");
 
+      // Sandbox bridges still add cursor CLI cold-start overhead, but the
+      // standard-2 tier now completes probes fast enough that 90s is ample.
+      const helloProbeTimeoutSec = Math.max(
+        1,
+        asNumber(config.helloProbeTimeoutSec, targetIsSandbox ? 90 : 45),
+      );
       const probe = await runAdapterExecutionTargetProcess(
         runId,
         target,
@@ -303,7 +317,7 @@ export async function testEnvironment(
         {
           cwd,
           env,
-          timeoutSec: 45,
+          timeoutSec: helloProbeTimeoutSec,
           graceSec: 5,
           onLog: async () => {},
         },

packages/adapters/grok-local/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@paperclipai/adapter-grok-local",
+  "version": "0.3.1",
+  "license": "MIT",
+  "homepage": "https://github.com/paperclipai/paperclip",
+  "bugs": {
+    "url": "https://github.com/paperclipai/paperclip/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paperclipai/paperclip",
+    "directory": "packages/adapters/grok-local"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server/index.ts",
+    "./ui": "./src/ui/index.ts",
+    "./cli": "./src/cli/index.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./server": {
+        "types": "./dist/server/index.d.ts",
+        "import": "./dist/server/index.js"
+      },
+      "./ui": {
+        "types": "./dist/ui/index.d.ts",
+        "import": "./dist/ui/index.js"
+      },
+      "./cli": {
+        "types": "./dist/cli/index.d.ts",
+        "import": "./dist/cli/index.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@paperclipai/adapter-utils": "workspace:*",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.7.3"
+  }
+}

packages/adapters/grok-local/src/cli/format-event.test.ts

@@ -0,0 +1,24 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { printGrokStreamEvent } from "./format-event.js";
+
+describe("printGrokStreamEvent", () => {
+  const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+  afterEach(() => {
+    spy.mockClear();
+  });
+
+  it("prints thought/text/end events", () => {
+    printGrokStreamEvent(JSON.stringify({ type: "thought", data: "Plan" }), false);
+    printGrokStreamEvent(JSON.stringify({ type: "text", data: "hello" }), false);
+    printGrokStreamEvent(JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1" }), false);
+
+    expect(spy.mock.calls.flat()).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("thinking: Plan"),
+        expect.stringContaining("assistant: hello"),
+        expect.stringContaining("Grok run completed"),
+      ]),
+    );
+  });
+});

packages/adapters/grok-local/src/cli/format-event.ts

@@ -0,0 +1,59 @@
+import pc from "picocolors";
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+export function printGrokStreamEvent(raw: string, _debug: boolean): void {
+  const line = raw.trim();
+  if (!line) return;
+
+  let parsed: Record<string, unknown> | null = null;
+  try {
+    parsed = JSON.parse(line) as Record<string, unknown>;
+  } catch {
+    console.log(line);
+    return;
+  }
+
+  const type = asString(parsed.type).trim();
+  if (type === "thought") {
+    const text = asString(parsed.data);
+    if (text) console.log(pc.gray(`thinking: ${text}`));
+    return;
+  }
+
+  if (type === "text") {
+    const text = asString(parsed.data);
+    if (text) console.log(pc.green(`assistant: ${text}`));
+    return;
+  }
+
+  if (type === "end") {
+    const stopReason = asString(parsed.stopReason);
+    const sessionId = asString(parsed.sessionId);
+    const details = [stopReason ? `stopReason=${stopReason}` : "", sessionId ? `session=${sessionId}` : ""]
+      .filter(Boolean)
+      .join(" ");
+    console.log(pc.blue(`Grok run completed${details ? ` (${details})` : ""}`));
+    return;
+  }
+
+  if (type === "error") {
+    const text =
+      asString(parsed.data) ||
+      asString(parsed.message) ||
+      asString(parsed.error) ||
+      "Grok error";
+    console.log(pc.red(`error: ${text}`));
+    return;
+  }
+
+  const payload = asRecord(parsed);
+  console.log(pc.gray(`event: ${type || "unknown"} ${payload ? JSON.stringify(payload) : line}`));
+}

packages/adapters/grok-local/src/cli/index.ts

@@ -0,0 +1 @@
+export { printGrokStreamEvent } from "./format-event.js";

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

@@ -0,0 +1,45 @@
+export const type = "grok_local";
+export const label = "Grok Build (local)";
+
+export const DEFAULT_GROK_LOCAL_MODEL = "grok-build";
+
+export const models = [
+  { id: DEFAULT_GROK_LOCAL_MODEL, label: DEFAULT_GROK_LOCAL_MODEL },
+];
+
+export const agentConfigurationDoc = `# grok_local agent configuration
+
+Adapter: grok_local
+
+Use when:
+- You want Paperclip to run the native Grok Build CLI locally on the host machine
+- You want resumable Grok sessions across heartbeats via \`--resume\`
+- You want Paperclip-managed instructions and skills staged into the execution workspace using Grok's native discovery paths (\`Agents.md\` and \`.claude/skills\`)
+
+Don't use when:
+- You need a webhook-style external invocation (use http or openclaw_gateway)
+- You only need a one-shot script without an AI coding agent loop (use process)
+- Grok CLI is not installed or authenticated on the machine that runs Paperclip
+
+Core fields:
+- cwd (string, optional): default absolute working directory fallback for the agent process (created if missing when possible)
+- instructionsFilePath (string, optional): absolute path to a markdown instructions file. Paperclip stages it into the execution workspace as \`Agents.md\` when safe, otherwise falls back to \`--rules @file\`
+- promptTemplate (string, optional): run prompt template
+- model (string, optional): Grok model id. Defaults to grok-build.
+- permissionMode (string, optional): Grok permission mode. Defaults to \`dontAsk\`
+- reasoningEffort (string, optional): Grok reasoning effort passed via \`--reasoning-effort\`
+- maxTurns (number, optional): maximum agent turns for the run
+- command (string, optional): defaults to "grok"
+- extraArgs (string[], optional): additional CLI args
+- env (object, optional): KEY=VALUE environment variables
+
+Operational fields:
+- timeoutSec (number, optional): run timeout in seconds
+- graceSec (number, optional): SIGTERM grace period in seconds
+
+Notes:
+- Runs use \`grok --single\` with \`--output-format streaming-json\`.
+- Sessions resume with \`--resume <sessionId>\` when the saved session cwd matches the current cwd.
+- Paperclip stages desired runtime skills into \`.claude/skills\` inside the execution workspace so Grok discovers them as project skills.
+- Use \`grok models\` to inspect authentication and available models on the host.
+`;

packages/adapters/grok-local/src/server/execute.test.ts

@@ -0,0 +1,187 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
+
+const ensureRuntimeInstalledMock = vi.hoisted(() => vi.fn(async () => {}));
+const ensureCommandMock = vi.hoisted(() => vi.fn(async () => {}));
+const prepareRuntimeMock = vi.hoisted(() => vi.fn(async () => ({
+  workspaceRemoteDir: null,
+  restoreWorkspace: async () => {},
+})));
+const resolveCommandForLogsMock = vi.hoisted(() => vi.fn(async () => "grok"));
+const runProcessMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@paperclipai/adapter-utils/execution-target", () => ({
+  adapterExecutionTargetIsRemote: () => false,
+  adapterExecutionTargetRemoteCwd: (_target: unknown, cwd: string) => cwd,
+  overrideAdapterExecutionTargetRemoteCwd: (target: unknown, _cwd: string) => target,
+  adapterExecutionTargetSessionIdentity: () => ({ kind: "local" }),
+  adapterExecutionTargetSessionMatches: () => true,
+  describeAdapterExecutionTarget: () => "local",
+  ensureAdapterExecutionTargetCommandResolvable: ensureCommandMock,
+  ensureAdapterExecutionTargetRuntimeCommandInstalled: ensureRuntimeInstalledMock,
+  prepareAdapterExecutionTargetRuntime: prepareRuntimeMock,
+  readAdapterExecutionTarget: ({ executionTarget }: { executionTarget?: unknown }) => executionTarget ?? { kind: "local" },
+  resolveAdapterExecutionTargetCommandForLogs: resolveCommandForLogsMock,
+  resolveAdapterExecutionTargetTimeoutSec: (_target: unknown, timeoutSec: number) => timeoutSec,
+  runAdapterExecutionTargetProcess: runProcessMock,
+}));
+
+import { execute } from "./execute.js";
+
+const tempRoots: string[] = [];
+
+async function makeTempRoot() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-grok-local-"));
+  tempRoots.push(root);
+  return root;
+}
+
+async function pathExists(candidate: string): Promise<boolean> {
+  return fs.access(candidate).then(() => true).catch(() => false);
+}
+
+describe("grok_local execute", () => {
+  beforeEach(() => {
+    ensureRuntimeInstalledMock.mockClear();
+    ensureCommandMock.mockClear();
+    prepareRuntimeMock.mockClear();
+    resolveCommandForLogsMock.mockClear();
+    runProcessMock.mockReset();
+  });
+
+  afterEach(async () => {
+    await Promise.all(tempRoots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true })));
+  });
+
+  it("stages Grok-native instructions and skills into the workspace for the run and cleans them up afterward", async () => {
+    const root = await makeTempRoot();
+    const instructionsPath = path.join(root, "managed", "AGENTS.md");
+    const skillSource = path.join(root, "runtime-skills", "paperclip");
+    await fs.mkdir(path.dirname(instructionsPath), { recursive: true });
+    await fs.writeFile(instructionsPath, "You are Grok.\n", "utf8");
+    await fs.mkdir(skillSource, { recursive: true });
+    await fs.writeFile(path.join(skillSource, "SKILL.md"), "---\nname: paperclip\ndescription: test\n---\n", "utf8");
+
+    runProcessMock.mockImplementation(async (_runId, _target, _command, args, options) => {
+      expect(args).toEqual(
+        expect.arrayContaining([
+          "--output-format",
+          "streaming-json",
+          "--always-approve",
+          "--permission-mode",
+          "dontAsk",
+        ]),
+      );
+      expect(await fs.readFile(path.join(root, "Agents.md"), "utf8")).toContain("You are Grok.");
+      expect(await pathExists(path.join(root, ".claude", "skills", "paperclip", "SKILL.md"))).toBe(true);
+      await options.onLog?.("stdout", '{"type":"text","data":"done"}\n');
+      return {
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        stdout: [
+          JSON.stringify({ type: "text", data: "done" }),
+          JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1", requestId: "req-1" }),
+        ].join("\n"),
+        stderr: "",
+      };
+    });
+
+    const logs: Array<{ stream: "stdout" | "stderr"; chunk: string }> = [];
+    const ctx: AdapterExecutionContext = {
+      runId: "run-1",
+      agent: {
+        id: "agent-1",
+        companyId: "company-1",
+        name: "Grok Agent",
+        adapterType: "grok_local",
+        adapterConfig: {},
+      },
+      runtime: {
+        sessionId: null,
+        sessionParams: null,
+        sessionDisplayId: null,
+        taskKey: null,
+      },
+      config: {
+        cwd: root,
+        instructionsFilePath: instructionsPath,
+        paperclipRuntimeSkills: [{
+          key: "paperclip",
+          runtimeName: "paperclip",
+          source: skillSource,
+          required: false,
+        }],
+        paperclipSkillSync: { desiredSkills: ["paperclip"] },
+      },
+      context: {},
+      authToken: "run-token",
+      onLog: async (stream: "stdout" | "stderr", chunk: string) => {
+        logs.push({ stream, chunk });
+      },
+    };
+
+    const result = await execute(ctx);
+
+    expect(result).toMatchObject({
+      exitCode: 0,
+      errorMessage: null,
+      summary: "done",
+      sessionId: "sess-1",
+      sessionDisplayId: "sess-1",
+    });
+    expect(await pathExists(path.join(root, "Agents.md"))).toBe(false);
+    expect(await pathExists(path.join(root, ".claude", "skills", "paperclip"))).toBe(false);
+    expect(logs.map((entry) => entry.chunk)).not.toEqual([]);
+  });
+
+  it("cleans up staged assets when setup fails before the Grok process starts", async () => {
+    const root = await makeTempRoot();
+    const instructionsPath = path.join(root, "managed", "AGENTS.md");
+    const skillSource = path.join(root, "runtime-skills", "paperclip");
+    await fs.mkdir(path.dirname(instructionsPath), { recursive: true });
+    await fs.writeFile(instructionsPath, "You are Grok.\n", "utf8");
+    await fs.mkdir(skillSource, { recursive: true });
+    await fs.writeFile(path.join(skillSource, "SKILL.md"), "---\nname: paperclip\ndescription: test\n---\n", "utf8");
+    ensureCommandMock.mockRejectedValueOnce(new Error("grok not installed"));
+
+    const ctx: AdapterExecutionContext = {
+      runId: "run-setup-fail",
+      agent: {
+        id: "agent-1",
+        companyId: "company-1",
+        name: "Grok Agent",
+        adapterType: "grok_local",
+        adapterConfig: {},
+      },
+      runtime: {
+        sessionId: null,
+        sessionParams: null,
+        sessionDisplayId: null,
+        taskKey: null,
+      },
+      config: {
+        cwd: root,
+        instructionsFilePath: instructionsPath,
+        paperclipRuntimeSkills: [{
+          key: "paperclip",
+          runtimeName: "paperclip",
+          source: skillSource,
+          required: false,
+        }],
+        paperclipSkillSync: { desiredSkills: ["paperclip"] },
+      },
+      context: {},
+      authToken: "run-token",
+      onLog: async () => {},
+    };
+
+    await expect(execute(ctx)).rejects.toThrow("grok not installed");
+    expect(runProcessMock).not.toHaveBeenCalled();
+    expect(await pathExists(path.join(root, "Agents.md"))).toBe(false);
+    expect(await pathExists(path.join(root, ".claude", "skills", "paperclip"))).toBe(false);
+  });
+});

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

@@ -0,0 +1,583 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
+import {
+  adapterExecutionTargetIsRemote,
+  adapterExecutionTargetRemoteCwd,
+  adapterExecutionTargetSessionIdentity,
+  adapterExecutionTargetSessionMatches,
+  describeAdapterExecutionTarget,
+  ensureAdapterExecutionTargetCommandResolvable,
+  ensureAdapterExecutionTargetRuntimeCommandInstalled,
+  overrideAdapterExecutionTargetRemoteCwd,
+  prepareAdapterExecutionTargetRuntime,
+  readAdapterExecutionTarget,
+  resolveAdapterExecutionTargetCommandForLogs,
+  resolveAdapterExecutionTargetTimeoutSec,
+  runAdapterExecutionTargetProcess,
+} from "@paperclipai/adapter-utils/execution-target";
+import {
+  asBoolean,
+  asNumber,
+  asString,
+  asStringArray,
+  buildInvocationEnvForLogs,
+  buildPaperclipEnv,
+  ensureAbsoluteDirectory,
+  ensurePathInEnv,
+  joinPromptSections,
+  materializePaperclipSkillCopy,
+  parseObject,
+  readPaperclipIssueWorkModeFromContext,
+  readPaperclipRuntimeSkillEntries,
+  renderTemplate,
+  renderPaperclipWakePrompt,
+  resolvePaperclipDesiredSkillNames,
+  stringifyPaperclipWakePayload,
+  refreshPaperclipWorkspaceEnvForExecution,
+  DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+} from "@paperclipai/adapter-utils/server-utils";
+import { DEFAULT_GROK_LOCAL_MODEL } from "../index.js";
+import { isGrokUnknownSessionError, parseGrokJsonl } from "./parse.js";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function firstNonEmptyLine(text: string): string {
+  return (
+    text
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find(Boolean) ?? ""
+  );
+}
+
+function hasNonEmptyEnvValue(env: Record<string, string>, key: string): boolean {
+  const raw = env[key];
+  return typeof raw === "string" && raw.trim().length > 0;
+}
+
+function renderPaperclipEnvNote(env: Record<string, string>): string {
+  const paperclipKeys = Object.keys(env)
+    .filter((key) => key.startsWith("PAPERCLIP_"))
+    .sort();
+  if (paperclipKeys.length === 0) return "";
+  return [
+    "Paperclip runtime note:",
+    `The following PAPERCLIP_* environment variables are available in this run: ${paperclipKeys.join(", ")}`,
+    "Do not assume these variables are missing without checking your shell environment.",
+    "",
+    "",
+  ].join("\n");
+}
+
+function renderApiAccessNote(env: Record<string, string>): string {
+  if (!hasNonEmptyEnvValue(env, "PAPERCLIP_API_URL") || !hasNonEmptyEnvValue(env, "PAPERCLIP_API_KEY")) return "";
+  return [
+    "Paperclip API access note:",
+    "Use shell commands with curl to make Paperclip API requests when needed.",
+    "Include X-Paperclip-Run-Id on mutating requests.",
+    "",
+    "",
+  ].join("\n");
+}
+
+type StageCleanup = {
+  kind: "file" | "dir";
+  path: string;
+};
+
+type StagedGrokAssets = {
+  cleanup: () => Promise<void>;
+  stagedSkillsCount: number;
+  stagedInstructionsPath: string | null;
+  rulesFilePath: string | null;
+};
+
+async function pathExists(candidate: string): Promise<boolean> {
+  return fs.access(candidate).then(() => true).catch(() => false);
+}
+
+async function stageGrokProjectAssets(input: {
+  cwd: string;
+  instructionsFilePath: string;
+  skillEntries: Array<{ key: string; runtimeName: string; source: string }>;
+  desiredSkillNames: string[];
+  onLog: AdapterExecutionContext["onLog"];
+}): Promise<StagedGrokAssets> {
+  const cleanup: StageCleanup[] = [];
+  const ensureCleanupDir = (candidate: string) => {
+    cleanup.push({ kind: "dir", path: candidate });
+  };
+  const ensureCleanupFile = (candidate: string) => {
+    cleanup.push({ kind: "file", path: candidate });
+  };
+
+  let stagedInstructionsPath: string | null = null;
+  let rulesFilePath: string | null = null;
+  let stagedSkillsCount = 0;
+
+  const instructionsTarget = path.join(input.cwd, "Agents.md");
+  if (input.instructionsFilePath) {
+    if (!await pathExists(instructionsTarget)) {
+      await fs.copyFile(input.instructionsFilePath, instructionsTarget);
+      ensureCleanupFile(instructionsTarget);
+      stagedInstructionsPath = instructionsTarget;
+    } else if (path.resolve(instructionsTarget) !== path.resolve(input.instructionsFilePath)) {
+      rulesFilePath = input.instructionsFilePath;
+      await input.onLog(
+        "stdout",
+        `[paperclip] Grok workspace already contains ${instructionsTarget}; using --rules @${input.instructionsFilePath} instead of overwriting it.\n`,
+      );
+    }
+  } else {
+    const canonicalAgents = path.join(input.cwd, "AGENTS.md");
+    if (!await pathExists(instructionsTarget) && await pathExists(canonicalAgents)) {
+      await fs.copyFile(canonicalAgents, instructionsTarget);
+      ensureCleanupFile(instructionsTarget);
+      stagedInstructionsPath = instructionsTarget;
+    }
+  }
+
+  const desiredSet = new Set(input.desiredSkillNames);
+  const selectedSkills = input.skillEntries.filter((entry) => desiredSet.has(entry.key));
+  if (selectedSkills.length > 0) {
+    const claudeDir = path.join(input.cwd, ".claude");
+    const skillsRoot = path.join(claudeDir, "skills");
+    if (!await pathExists(claudeDir)) {
+      await fs.mkdir(claudeDir, { recursive: true });
+      ensureCleanupDir(claudeDir);
+    }
+    if (!await pathExists(skillsRoot)) {
+      await fs.mkdir(skillsRoot, { recursive: true });
+      ensureCleanupDir(skillsRoot);
+    }
+
+    for (const skill of selectedSkills) {
+      const target = path.join(skillsRoot, skill.runtimeName);
+      if (await pathExists(target)) {
+        await input.onLog(
+          "stdout",
+          `[paperclip] Grok skill target already exists at ${target}; leaving it unchanged.\n`,
+        );
+        continue;
+      }
+      await materializePaperclipSkillCopy(skill.source, target);
+      ensureCleanupDir(target);
+      stagedSkillsCount += 1;
+    }
+  }
+
+  return {
+    stagedSkillsCount,
+    stagedInstructionsPath,
+    rulesFilePath,
+    cleanup: async () => {
+      for (const entry of [...cleanup].reverse()) {
+        if (entry.kind === "file") {
+          await fs.rm(entry.path, { force: true }).catch(() => undefined);
+          continue;
+        }
+        await fs.rm(entry.path, { recursive: true, force: true }).catch(() => undefined);
+      }
+    },
+  };
+}
+
+function resolveBillingType(env: Record<string, string>): "api" | "subscription" {
+  return hasNonEmptyEnvValue(env, "XAI_API_KEY") ? "api" : "subscription";
+}
+
+export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
+  const { runId, agent, runtime, config, context, onLog, onMeta, onSpawn, authToken } = ctx;
+  const executionTarget = readAdapterExecutionTarget({
+    executionTarget: ctx.executionTarget,
+    legacyRemoteExecution: ctx.executionTransport?.remoteExecution,
+  });
+  const executionTargetIsRemote = adapterExecutionTargetIsRemote(executionTarget);
+
+  const promptTemplate = asString(
+    config.promptTemplate,
+    DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,
+  );
+  const command = asString(config.command, "grok");
+  const model = asString(config.model, DEFAULT_GROK_LOCAL_MODEL).trim();
+  const permissionMode = asString(config.permissionMode, "dontAsk").trim() || "dontAsk";
+  const reasoningEffort = asString(config.reasoningEffort, "").trim();
+  const maxTurns = asNumber(config.maxTurns, 0);
+  const alwaysApprove = asBoolean(config.alwaysApprove, true);
+  const disableWebSearch = asBoolean(config.disableWebSearch, true);
+
+  const workspaceContext = parseObject(context.paperclipWorkspace);
+  const workspaceCwd = asString(workspaceContext.cwd, "");
+  const workspaceSource = asString(workspaceContext.source, "");
+  const workspaceId = asString(workspaceContext.workspaceId, "");
+  const workspaceRepoUrl = asString(workspaceContext.repoUrl, "");
+  const workspaceRepoRef = asString(workspaceContext.repoRef, "");
+  const agentHome = asString(workspaceContext.agentHome, "");
+  const workspaceHints = Array.isArray(context.paperclipWorkspaces)
+    ? context.paperclipWorkspaces.filter(
+        (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null,
+      )
+    : [];
+  const configuredCwd = asString(config.cwd, "");
+  const useConfiguredInsteadOfAgentHome = workspaceSource === "agent_home" && configuredCwd.length > 0;
+  const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
+  const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
+  let effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);
+  await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
+
+  const grokSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const desiredGrokSkillNames = resolvePaperclipDesiredSkillNames(config, grokSkillEntries);
+  const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
+  const stagedAssets = await stageGrokProjectAssets({
+    cwd,
+    instructionsFilePath,
+    skillEntries: grokSkillEntries,
+    desiredSkillNames: desiredGrokSkillNames,
+    onLog,
+  });
+  let restoreRemoteWorkspace: (() => Promise<void>) | null = null;
+
+  try {
+    const envConfig = parseObject(config.env);
+    const hasExplicitApiKey =
+      typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;
+    const env: Record<string, string> = { ...buildPaperclipEnv(agent) };
+    env.PAPERCLIP_RUN_ID = runId;
+    const wakeTaskId =
+      (typeof context.taskId === "string" && context.taskId.trim().length > 0 && context.taskId.trim()) ||
+      (typeof context.issueId === "string" && context.issueId.trim().length > 0 && context.issueId.trim()) ||
+      null;
+    const wakeReason =
+      typeof context.wakeReason === "string" && context.wakeReason.trim().length > 0
+        ? context.wakeReason.trim()
+        : null;
+    const wakeCommentId =
+      (typeof context.wakeCommentId === "string" && context.wakeCommentId.trim().length > 0 && context.wakeCommentId.trim()) ||
+      (typeof context.commentId === "string" && context.commentId.trim().length > 0 && context.commentId.trim()) ||
+      null;
+    const approvalId =
+      typeof context.approvalId === "string" && context.approvalId.trim().length > 0
+        ? context.approvalId.trim()
+        : null;
+    const approvalStatus =
+      typeof context.approvalStatus === "string" && context.approvalStatus.trim().length > 0
+        ? context.approvalStatus.trim()
+        : null;
+    const linkedIssueIds = Array.isArray(context.issueIds)
+      ? context.issueIds.filter((value: unknown): value is string => typeof value === "string" && value.trim().length > 0)
+      : [];
+    const wakePayloadJson = stringifyPaperclipWakePayload(context.paperclipWake);
+    const issueWorkMode = readPaperclipIssueWorkModeFromContext(context);
+    if (wakeTaskId) env.PAPERCLIP_TASK_ID = wakeTaskId;
+    if (issueWorkMode) env.PAPERCLIP_ISSUE_WORK_MODE = issueWorkMode;
+    if (wakeReason) env.PAPERCLIP_WAKE_REASON = wakeReason;
+    if (wakeCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = wakeCommentId;
+    if (approvalId) env.PAPERCLIP_APPROVAL_ID = approvalId;
+    if (approvalStatus) env.PAPERCLIP_APPROVAL_STATUS = approvalStatus;
+    if (linkedIssueIds.length > 0) env.PAPERCLIP_LINKED_ISSUE_IDS = linkedIssueIds.join(",");
+    if (wakePayloadJson) env.PAPERCLIP_WAKE_PAYLOAD_JSON = wakePayloadJson;
+    refreshPaperclipWorkspaceEnvForExecution({
+      env,
+      envConfig,
+      workspaceCwd: effectiveWorkspaceCwd,
+      workspaceSource,
+      workspaceId,
+      workspaceRepoUrl,
+      workspaceRepoRef,
+      workspaceHints,
+      agentHome,
+      executionTargetIsRemote,
+      executionCwd: effectiveExecutionCwd,
+    });
+    if (!hasExplicitApiKey && authToken) {
+      env.PAPERCLIP_API_KEY = authToken;
+    }
+
+    const timeoutSec = resolveAdapterExecutionTargetTimeoutSec(
+      executionTarget,
+      asNumber(config.timeoutSec, 0),
+    );
+    const graceSec = asNumber(config.graceSec, 20);
+    await ensureAdapterExecutionTargetRuntimeCommandInstalled({
+      runId,
+      target: executionTarget,
+      installCommand: ctx.runtimeCommandSpec?.installCommand,
+      detectCommand: ctx.runtimeCommandSpec?.detectCommand,
+      cwd,
+      env,
+      timeoutSec,
+      graceSec,
+      onLog,
+    });
+
+    if (executionTargetIsRemote) {
+      await onLog(
+        "stdout",
+        `[paperclip] Syncing Grok workspace to ${describeAdapterExecutionTarget(executionTarget)}.\n`,
+      );
+      const preparedExecutionTargetRuntime = await prepareAdapterExecutionTargetRuntime({
+        runId,
+        target: executionTarget,
+        adapterKey: "grok",
+        workspaceLocalDir: cwd,
+        timeoutSec,
+        installCommand: ctx.runtimeCommandSpec?.installCommand ?? null,
+        detectCommand: ctx.runtimeCommandSpec?.detectCommand ?? command,
+      });
+      restoreRemoteWorkspace = () => preparedExecutionTargetRuntime.restoreWorkspace();
+      effectiveExecutionCwd = preparedExecutionTargetRuntime.workspaceRemoteDir ?? effectiveExecutionCwd;
+      refreshPaperclipWorkspaceEnvForExecution({
+        env,
+        envConfig,
+        workspaceCwd: effectiveWorkspaceCwd,
+        workspaceSource,
+        workspaceId,
+        workspaceRepoUrl,
+        workspaceRepoRef,
+        workspaceHints,
+        agentHome,
+        executionTargetIsRemote,
+        executionCwd: effectiveExecutionCwd,
+      });
+    }
+
+    const runtimeExecutionTarget = overrideAdapterExecutionTargetRemoteCwd(executionTarget, effectiveExecutionCwd);
+    const effectiveEnv = Object.fromEntries(
+      Object.entries({ ...process.env, ...env }).filter(
+        (entry): entry is [string, string] => typeof entry[1] === "string",
+      ),
+    );
+    const runtimeEnv = ensurePathInEnv(effectiveEnv);
+    await ensureAdapterExecutionTargetCommandResolvable(command, executionTarget, cwd, runtimeEnv, {
+      installCommand: ctx.runtimeCommandSpec?.installCommand ?? null,
+      timeoutSec,
+    });
+    const resolvedCommand = await resolveAdapterExecutionTargetCommandForLogs(command, executionTarget, cwd, runtimeEnv);
+    const loggedEnv = buildInvocationEnvForLogs(env, {
+      runtimeEnv,
+      includeRuntimeKeys: ["HOME"],
+      resolvedCommand,
+    });
+    const billingType = resolveBillingType(effectiveEnv);
+
+    const runtimeSessionParams = parseObject(runtime.sessionParams);
+    const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
+    const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
+    const runtimeRemoteExecution = parseObject(runtimeSessionParams.remoteExecution);
+    const canResumeSession =
+      runtimeSessionId.length > 0 &&
+      (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(effectiveExecutionCwd)) &&
+      adapterExecutionTargetSessionMatches(runtimeRemoteExecution, runtimeExecutionTarget);
+    const sessionId = canResumeSession ? runtimeSessionId : null;
+    if (executionTargetIsRemote && runtimeSessionId && !canResumeSession) {
+      await onLog(
+        "stdout",
+        `[paperclip] Grok session "${runtimeSessionId}" does not match the current remote execution identity and will not be resumed in "${effectiveExecutionCwd}". Starting a fresh remote session.\n`,
+      );
+    } else if (runtimeSessionId && !canResumeSession) {
+      await onLog(
+        "stdout",
+        `[paperclip] Grok session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${effectiveExecutionCwd}".\n`,
+      );
+    }
+
+    const commandNotes = (() => {
+      const notes: string[] = ["Prompt is passed to Grok via --single in headless mode."];
+      if (alwaysApprove) notes.push("Added --always-approve for unattended execution.");
+      if (stagedAssets.stagedInstructionsPath) {
+        notes.push(`Staged project instructions at ${stagedAssets.stagedInstructionsPath} for native Grok discovery.`);
+      }
+      if (stagedAssets.rulesFilePath) {
+        notes.push(`Applied fallback instructions via --rules @${stagedAssets.rulesFilePath}.`);
+      }
+      if (stagedAssets.stagedSkillsCount > 0) {
+        notes.push(`Staged ${stagedAssets.stagedSkillsCount} Paperclip skill(s) into .claude/skills for native Grok discovery.`);
+      }
+      return notes;
+    })();
+
+    const templateData = {
+      agentId: agent.id,
+      companyId: agent.companyId,
+      runId,
+      company: { id: agent.companyId },
+      agent,
+      run: { id: runId, source: "on_demand" },
+      context,
+    };
+    const wakePrompt = renderPaperclipWakePrompt(context.paperclipWake, { resumedSession: Boolean(sessionId) });
+    const shouldUseResumeDeltaPrompt = Boolean(sessionId) && wakePrompt.length > 0;
+    const renderedPrompt = shouldUseResumeDeltaPrompt ? "" : renderTemplate(promptTemplate, templateData);
+    const sessionHandoffNote = asString(context.paperclipSessionHandoffMarkdown, "").trim();
+    const paperclipEnvNote = renderPaperclipEnvNote(env);
+    const apiAccessNote = renderApiAccessNote(env);
+    const prompt = joinPromptSections([
+      wakePrompt,
+      sessionHandoffNote,
+      paperclipEnvNote,
+      apiAccessNote,
+      renderedPrompt,
+    ]);
+    const promptMetrics = {
+      promptChars: prompt.length,
+      wakePromptChars: wakePrompt.length,
+      sessionHandoffChars: sessionHandoffNote.length,
+      runtimeNoteChars: paperclipEnvNote.length + apiAccessNote.length,
+      heartbeatPromptChars: renderedPrompt.length,
+    };
+
+    const buildArgs = (resumeSessionId: string | null) => {
+      const args = ["--cwd", effectiveExecutionCwd, "--output-format", "streaming-json"];
+      if (resumeSessionId) args.push("--resume", resumeSessionId);
+      if (model && model !== DEFAULT_GROK_LOCAL_MODEL) args.push("--model", model);
+      if (reasoningEffort) args.push("--reasoning-effort", reasoningEffort);
+      if (maxTurns > 0) args.push("--max-turns", String(maxTurns));
+      if (permissionMode) args.push("--permission-mode", permissionMode);
+      if (alwaysApprove) args.push("--always-approve");
+      if (disableWebSearch) args.push("--disable-web-search");
+      if (stagedAssets.rulesFilePath) args.push("--rules", `@${stagedAssets.rulesFilePath}`);
+      const extraArgs = (() => {
+        const fromExtraArgs = asStringArray(config.extraArgs);
+        if (fromExtraArgs.length > 0) return fromExtraArgs;
+        return asStringArray(config.args);
+      })();
+      if (extraArgs.length > 0) args.push(...extraArgs);
+      args.push("--single", prompt);
+      return args;
+    };
+
+    const runAttempt = async (resumeSessionId: string | null) => {
+      const args = buildArgs(resumeSessionId);
+      if (onMeta) {
+        await onMeta({
+          adapterType: "grok_local",
+          command: resolvedCommand,
+          cwd: effectiveExecutionCwd,
+          commandNotes,
+          commandArgs: args.map((value, index) => (
+            index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value
+          )),
+          env: loggedEnv,
+          prompt,
+          promptMetrics,
+          context,
+        });
+      }
+
+      const proc = await runAdapterExecutionTargetProcess(runId, runtimeExecutionTarget, command, args, {
+        cwd,
+        env,
+        timeoutSec,
+        graceSec,
+        onSpawn,
+        onLog,
+      });
+      return {
+        proc,
+        parsed: parseGrokJsonl(proc.stdout),
+      };
+    };
+
+    const toResult = (
+      attempt: {
+        proc: {
+          exitCode: number | null;
+          signal: string | null;
+          timedOut: boolean;
+          stdout: string;
+          stderr: string;
+        };
+        parsed: ReturnType<typeof parseGrokJsonl>;
+      },
+      clearSessionOnMissingSession = false,
+      isRetry = false,
+    ): AdapterExecutionResult => {
+      if (attempt.proc.timedOut) {
+        return {
+          exitCode: attempt.proc.exitCode,
+          signal: attempt.proc.signal,
+          timedOut: true,
+          errorMessage: `Timed out after ${timeoutSec}s`,
+          clearSession: clearSessionOnMissingSession,
+        };
+      }
+
+      const failed = (attempt.proc.exitCode ?? 0) !== 0;
+      const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
+      const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
+      const fallbackErrorMessage =
+        parsedError ||
+        stderrLine ||
+        `Grok exited with code ${attempt.proc.exitCode ?? -1}`;
+
+      const canFallbackToRuntimeSession = !isRetry;
+      const resolvedSessionId = attempt.parsed.sessionId
+        ?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
+      const resolvedSessionParams = resolvedSessionId
+        ? ({
+          sessionId: resolvedSessionId,
+          cwd: effectiveExecutionCwd,
+          ...(workspaceId ? { workspaceId } : {}),
+          ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
+          ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
+          ...(executionTargetIsRemote
+            ? {
+                remoteExecution: adapterExecutionTargetSessionIdentity(runtimeExecutionTarget),
+              }
+            : {}),
+        } as Record<string, unknown>)
+        : null;
+
+      return {
+        exitCode: attempt.proc.exitCode,
+        signal: attempt.proc.signal,
+        timedOut: false,
+        errorMessage: failed ? fallbackErrorMessage : null,
+        usage: {
+          inputTokens: 0,
+          outputTokens: 0,
+          cachedInputTokens: 0,
+        },
+        sessionId: resolvedSessionId,
+        sessionParams: resolvedSessionParams,
+        sessionDisplayId: resolvedSessionId,
+        provider: "xai",
+        biller: billingType === "api" ? "xai" : "grok",
+        model,
+        billingType,
+        costUsd: null,
+        resultJson: {
+          stopReason: attempt.parsed.stopReason,
+          requestId: attempt.parsed.requestId,
+          ...(failed ? { stderr: attempt.proc.stderr } : {}),
+        },
+        summary: attempt.parsed.summary,
+        clearSession: Boolean(clearSessionOnMissingSession && !resolvedSessionId),
+      };
+    };
+
+    const initial = await runAttempt(sessionId);
+    if (
+      sessionId &&
+      !initial.proc.timedOut &&
+      (initial.proc.exitCode ?? 0) !== 0 &&
+      isGrokUnknownSessionError(initial.proc.stdout, initial.proc.stderr)
+    ) {
+      await onLog(
+        "stdout",
+        `[paperclip] Grok resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
+      );
+      const retry = await runAttempt(null);
+      return toResult(retry, true, true);
+    }
+
+    return toResult(initial);
+  } finally {
+    await Promise.all([
+      restoreRemoteWorkspace?.(),
+      stagedAssets.cleanup(),
+    ]);
+  }
+}

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

@@ -0,0 +1,66 @@
+import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";
+
+function readNonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+export const sessionCodec: AdapterSessionCodec = {
+  deserialize(raw: unknown) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+    const record = raw as Record<string, unknown>;
+    const sessionId =
+      readNonEmptyString(record.sessionId) ??
+      readNonEmptyString(record.session_id) ??
+      readNonEmptyString(record.sessionID);
+    if (!sessionId) return null;
+    const cwd =
+      readNonEmptyString(record.cwd) ??
+      readNonEmptyString(record.workdir) ??
+      readNonEmptyString(record.folder);
+    const workspaceId = readNonEmptyString(record.workspaceId) ?? readNonEmptyString(record.workspace_id);
+    const repoUrl = readNonEmptyString(record.repoUrl) ?? readNonEmptyString(record.repo_url);
+    const repoRef = readNonEmptyString(record.repoRef) ?? readNonEmptyString(record.repo_ref);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+      ...(workspaceId ? { workspaceId } : {}),
+      ...(repoUrl ? { repoUrl } : {}),
+      ...(repoRef ? { repoRef } : {}),
+    };
+  },
+  serialize(params: Record<string, unknown> | null) {
+    if (!params) return null;
+    const sessionId =
+      readNonEmptyString(params.sessionId) ??
+      readNonEmptyString(params.session_id) ??
+      readNonEmptyString(params.sessionID);
+    if (!sessionId) return null;
+    const cwd =
+      readNonEmptyString(params.cwd) ??
+      readNonEmptyString(params.workdir) ??
+      readNonEmptyString(params.folder);
+    const workspaceId = readNonEmptyString(params.workspaceId) ?? readNonEmptyString(params.workspace_id);
+    const repoUrl = readNonEmptyString(params.repoUrl) ?? readNonEmptyString(params.repo_url);
+    const repoRef = readNonEmptyString(params.repoRef) ?? readNonEmptyString(params.repo_ref);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+      ...(workspaceId ? { workspaceId } : {}),
+      ...(repoUrl ? { repoUrl } : {}),
+      ...(repoRef ? { repoRef } : {}),
+    };
+  },
+  getDisplayId(params: Record<string, unknown> | null) {
+    if (!params) return null;
+    return (
+      readNonEmptyString(params.sessionId) ??
+      readNonEmptyString(params.session_id) ??
+      readNonEmptyString(params.sessionID)
+    );
+  },
+};
+
+export { execute } from "./execute.js";
+export { listGrokSkills, syncGrokSkills } from "./skills.js";
+export { testEnvironment } from "./test.js";
+export { parseGrokJsonl, isGrokUnknownSessionError } from "./parse.js";

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

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { isGrokUnknownSessionError, parseGrokJsonl } from "./parse.js";
+
+describe("parseGrokJsonl", () => {
+  it("collects streamed thought/text content and final session metadata", () => {
+    const parsed = parseGrokJsonl([
+      JSON.stringify({ type: "thought", data: "Plan" }),
+      JSON.stringify({ type: "thought", data: " first." }),
+      JSON.stringify({ type: "text", data: "hel" }),
+      JSON.stringify({ type: "text", data: "lo" }),
+      JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1", requestId: "req-1" }),
+    ].join("\n"));
+
+    expect(parsed).toEqual({
+      sessionId: "sess-1",
+      summary: "hello",
+      thought: "Plan first.",
+      errorMessage: null,
+      stopReason: "EndTurn",
+      requestId: "req-1",
+    });
+  });
+
+  it("reads structured error payloads", () => {
+    const parsed = parseGrokJsonl([
+      JSON.stringify({ type: "error", error: { message: "Authentication required" } }),
+    ].join("\n"));
+
+    expect(parsed.errorMessage).toBe("Authentication required");
+  });
+
+  it("separates reasoning turns that grok streaming-json glues together", () => {
+    // PAPA-349: at turn boundaries grok drops the newline between turns; the
+    // aggregated thought should still read as two paragraphs.
+    const parsed = parseGrokJsonl([
+      JSON.stringify({ type: "thought", data: "The user uses `" }),
+      JSON.stringify({ type: "thought", data: "ls" }),
+      JSON.stringify({ type: "thought", data: "`" }),
+      JSON.stringify({ type: "thought", data: "The" }),
+      JSON.stringify({ type: "thought", data: " `" }),
+      JSON.stringify({ type: "thought", data: "ls" }),
+      JSON.stringify({ type: "thought", data: "`" }),
+      JSON.stringify({ type: "thought", data: " returned" }),
+      JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1" }),
+    ].join("\n"));
+
+    expect(parsed.thought).toBe("The user uses `ls`\nThe `ls` returned");
+  });
+
+  it("preserves assistant `text` chunks verbatim (no boundary heuristic)", () => {
+    // PAPA-349 review feedback: the turn-boundary helper is scoped to the
+    // reasoning stream only. Final assistant text is stored unmodified so
+    // user-visible responses cannot be reshaped by the heuristic.
+    const parsed = parseGrokJsonl([
+      JSON.stringify({ type: "text", data: "Done." }),
+      JSON.stringify({ type: "text", data: "Next" }),
+      JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1" }),
+    ].join("\n"));
+
+    expect(parsed.summary).toBe("Done.Next");
+  });
+});
+
+describe("isGrokUnknownSessionError", () => {
+  it("detects stale resume failures", () => {
+    expect(isGrokUnknownSessionError("", "session not found")).toBe(true);
+    expect(isGrokUnknownSessionError("", "everything fine")).toBe(false);
+  });
+});

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

@@ -0,0 +1,89 @@
+import { asString, parseJson, parseObject } from "@paperclipai/adapter-utils/server-utils";
+import { applyTurnBoundary, createTurnBoundaryState } from "../shared/turn-boundary.js";
+
+export interface ParsedGrokJsonl {
+  sessionId: string | null;
+  summary: string;
+  thought: string;
+  errorMessage: string | null;
+  stopReason: string | null;
+  requestId: string | null;
+}
+
+function errorText(value: unknown): string {
+  if (typeof value === "string") return value;
+  const rec = parseObject(value);
+  const message =
+    asString(rec.message, "").trim() ||
+    asString(rec.error, "").trim() ||
+    asString(rec.detail, "").trim() ||
+    asString(rec.code, "").trim();
+  if (message) return message;
+  try {
+    return JSON.stringify(rec);
+  } catch {
+    return "";
+  }
+}
+
+export function parseGrokJsonl(stdout: string): ParsedGrokJsonl {
+  let sessionId: string | null = null;
+  let stopReason: string | null = null;
+  let requestId: string | null = null;
+  let errorMessage: string | null = null;
+  const thoughtParts: string[] = [];
+  const textParts: string[] = [];
+  const thoughtBoundary = createTurnBoundaryState();
+
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    const event = parseJson(line);
+    if (!event) continue;
+
+    const type = asString(event.type, "").trim();
+    if (type === "thought") {
+      const text = asString(event.data, "");
+      if (text) thoughtParts.push(applyTurnBoundary(thoughtBoundary, text));
+      continue;
+    }
+
+    if (type === "text") {
+      const text = asString(event.data, "");
+      if (text) textParts.push(text);
+      continue;
+    }
+
+    if (type === "end") {
+      sessionId = asString(event.sessionId, "").trim() || sessionId;
+      stopReason = asString(event.stopReason, "").trim() || stopReason;
+      requestId = asString(event.requestId, "").trim() || requestId;
+      continue;
+    }
+
+    if (type === "error") {
+      const text = errorText(event.error ?? event.message ?? event.detail ?? event.data).trim();
+      if (text) errorMessage = text;
+    }
+  }
+
+  return {
+    sessionId,
+    summary: textParts.join("").trim(),
+    thought: thoughtParts.join("").trim(),
+    errorMessage,
+    stopReason,
+    requestId,
+  };
+}
+
+export function isGrokUnknownSessionError(stdout: string, stderr: string): boolean {
+  const haystack = `${stdout}\n${stderr}`
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .join("\n");
+
+  return /unknown\s+session|session(?:\s+.*)?\s+not\s+found|resume\s+.*\s+not\s+found|invalid\s+session/i.test(haystack);
+}

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

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

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

@@ -0,0 +1,142 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+const ensureDirectoryMock = vi.hoisted(() => vi.fn(async () => {}));
+const ensureCommandMock = vi.hoisted(() => vi.fn(async () => {}));
+const runProcessMock = vi.hoisted(() => vi.fn());
+
+vi.mock("@paperclipai/adapter-utils/execution-target", () => ({
+  describeAdapterExecutionTarget: () => "local",
+  ensureAdapterExecutionTargetCommandResolvable: ensureCommandMock,
+  ensureAdapterExecutionTargetDirectory: ensureDirectoryMock,
+  resolveAdapterExecutionTargetCwd: (_target: unknown, configuredCwd: string, fallbackCwd: string) =>
+    configuredCwd || fallbackCwd,
+  runAdapterExecutionTargetProcess: runProcessMock,
+}));
+
+import { parseGrokModelsOutput, testEnvironment } from "./test.js";
+
+describe("parseGrokModelsOutput", () => {
+  it("extracts auth state and models from `grok models` output", () => {
+    expect(parseGrokModelsOutput([
+      "You are logged in with grok.com.",
+      "",
+      "Default model: grok-build",
+      "",
+      "Available models:",
+      "  * grok-build (default)",
+      "  * grok-code",
+    ].join("\n"))).toEqual({
+      authenticated: true,
+      defaultModel: "grok-build",
+      models: ["grok-build", "grok-code"],
+    });
+  });
+});
+
+describe("grok_local testEnvironment", () => {
+  beforeEach(() => {
+    ensureDirectoryMock.mockClear();
+    ensureCommandMock.mockClear();
+    runProcessMock.mockReset();
+  });
+
+  it("reports a healthy authenticated host with a working hello probe", async () => {
+    runProcessMock
+      .mockResolvedValueOnce({
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        stdout: [
+          "You are logged in with grok.com.",
+          "",
+          "Default model: grok-build",
+          "",
+          "Available models:",
+          "  * grok-build (default)",
+        ].join("\n"),
+        stderr: "",
+      })
+      .mockResolvedValueOnce({
+        exitCode: 0,
+        signal: null,
+        timedOut: false,
+        stdout: [
+          JSON.stringify({ type: "text", data: "hello" }),
+          JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1", requestId: "req-1" }),
+        ].join("\n"),
+        stderr: "",
+      });
+
+    const result = await testEnvironment({
+      companyId: "company-1",
+      adapterType: "grok_local",
+      config: {
+        command: "grok",
+        cwd: "/tmp/project",
+        model: "grok-build",
+      },
+    });
+
+    expect(result.status).toBe("pass");
+    expect(result.checks.map((check: { code: string }) => check.code)).toEqual(
+      expect.arrayContaining([
+        "grok_command_resolvable",
+        "grok_models_probe_passed",
+        "grok_model_configured",
+        "grok_hello_probe_passed",
+      ]),
+    );
+    expect(runProcessMock).toHaveBeenNthCalledWith(
+      2,
+      expect.any(String),
+      null,
+      "grok",
+      expect.arrayContaining([
+        "--output-format",
+        "streaming-json",
+        "--always-approve",
+        "--permission-mode",
+        "dontAsk",
+        "--disable-web-search",
+        "--single",
+        "Respond with exactly hello.",
+      ]),
+      expect.any(Object),
+    );
+  });
+
+  it("downgrades auth failures to warnings", async () => {
+    runProcessMock
+      .mockResolvedValueOnce({
+        exitCode: 1,
+        signal: null,
+        timedOut: false,
+        stdout: "",
+        stderr: "Not logged in. Run `grok login`.",
+      })
+      .mockResolvedValueOnce({
+        exitCode: 1,
+        signal: null,
+        timedOut: false,
+        stdout: "",
+        stderr: "Not logged in. Run `grok login`.",
+      });
+
+    const result = await testEnvironment({
+      companyId: "company-1",
+      adapterType: "grok_local",
+      config: {
+        command: "grok",
+        cwd: "/tmp/project",
+      },
+    });
+
+    expect(result.status).toBe("warn");
+    expect(result.checks.map((check: { code: string }) => check.code)).toEqual(
+      expect.arrayContaining([
+        "grok_auth_required",
+        "grok_hello_probe_auth_required",
+      ]),
+    );
+  });
+});

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

@@ -0,0 +1,313 @@
+import type {
+  AdapterEnvironmentCheck,
+  AdapterEnvironmentTestContext,
+  AdapterEnvironmentTestResult,
+} from "@paperclipai/adapter-utils";
+import {
+  asNumber,
+  asString,
+  asStringArray,
+  ensurePathInEnv,
+  parseObject,
+} from "@paperclipai/adapter-utils/server-utils";
+import {
+  describeAdapterExecutionTarget,
+  ensureAdapterExecutionTargetCommandResolvable,
+  ensureAdapterExecutionTargetDirectory,
+  resolveAdapterExecutionTargetCwd,
+  runAdapterExecutionTargetProcess,
+} from "@paperclipai/adapter-utils/execution-target";
+import { DEFAULT_GROK_LOCAL_MODEL } from "../index.js";
+import { parseGrokJsonl } from "./parse.js";
+
+export interface GrokModelsProbe {
+  authenticated: boolean;
+  defaultModel: string | null;
+  models: string[];
+}
+
+function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
+  if (checks.some((check) => check.level === "error")) return "fail";
+  if (checks.some((check) => check.level === "warn")) return "warn";
+  return "pass";
+}
+
+function firstNonEmptyLine(text: string): string {
+  return (
+    text
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .find(Boolean) ?? ""
+  );
+}
+
+function summarizeProbeDetail(stdout: string, stderr: string, parsedError: string | null): string | null {
+  const raw = parsedError?.trim() || firstNonEmptyLine(stderr) || firstNonEmptyLine(stdout);
+  if (!raw) return null;
+  const clean = raw.replace(/\s+/g, " ").trim();
+  const max = 240;
+  return clean.length > max ? `${clean.slice(0, max - 3)}...` : clean;
+}
+
+function normalizeEnv(input: unknown): Record<string, string> {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return {};
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
+    if (typeof value === "string") env[key] = value;
+  }
+  return env;
+}
+
+const GROK_AUTH_REQUIRED_RE =
+  /(?:not\s+logged\s+in|login\s+required|run\s+`?grok\s+login`?|authentication\s+required|unauthorized|invalid\s+credentials)/i;
+
+export function parseGrokModelsOutput(stdout: string): GrokModelsProbe {
+  const trimmedLines = stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const models: string[] = [];
+  let defaultModel: string | null = null;
+  let authenticated = false;
+  let inModelsBlock = false;
+
+  for (const line of trimmedLines) {
+    if (/logged in/i.test(line)) authenticated = true;
+    const defaultMatch = /^Default model:\s*(.+)$/i.exec(line);
+    if (defaultMatch?.[1]) {
+      defaultModel = defaultMatch[1].trim();
+      continue;
+    }
+    if (/^Available models:/i.test(line)) {
+      inModelsBlock = true;
+      continue;
+    }
+    if (!inModelsBlock) continue;
+    const bulletMatch = /^[*-]\s*(.+?)(?:\s+\(default\))?$/.exec(line);
+    if (bulletMatch?.[1]) {
+      models.push(bulletMatch[1].trim());
+      continue;
+    }
+    if (line.length > 0) {
+      models.push(line.replace(/\s+\(default\)$/, "").trim());
+    }
+  }
+
+  return {
+    authenticated,
+    defaultModel,
+    models: Array.from(new Set(models.filter(Boolean))),
+  };
+}
+
+export async function testEnvironment(
+  ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+  const checks: AdapterEnvironmentCheck[] = [];
+  const config = parseObject(ctx.config);
+  const command = asString(config.command, "grok");
+  const target = ctx.executionTarget ?? null;
+  const targetIsRemote = target?.kind === "remote";
+  const cwd = resolveAdapterExecutionTargetCwd(target, asString(config.cwd, ""), process.cwd());
+  const targetLabel = targetIsRemote
+    ? ctx.environmentName ?? describeAdapterExecutionTarget(target)
+    : null;
+  const runId = `grok-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+  if (targetLabel) {
+    checks.push({
+      code: "grok_environment_target",
+      level: "info",
+      message: `Probing inside environment: ${targetLabel}`,
+    });
+  }
+
+  try {
+    await ensureAdapterExecutionTargetDirectory(runId, target, cwd, {
+      cwd,
+      env: {},
+      createIfMissing: true,
+    });
+    checks.push({
+      code: "grok_cwd_valid",
+      level: "info",
+      message: `Working directory is valid: ${cwd}`,
+    });
+  } catch (err) {
+    checks.push({
+      code: "grok_cwd_invalid",
+      level: "error",
+      message: err instanceof Error ? err.message : "Invalid working directory",
+      detail: cwd,
+    });
+  }
+
+  const env = normalizeEnv(config.env);
+  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
+
+  try {
+    await ensureAdapterExecutionTargetCommandResolvable(command, target, cwd, runtimeEnv);
+    checks.push({
+      code: "grok_command_resolvable",
+      level: "info",
+      message: `Command is executable: ${command}`,
+    });
+  } catch (err) {
+    checks.push({
+      code: "grok_command_unresolvable",
+      level: "error",
+      message: err instanceof Error ? err.message : "Command is not executable",
+      detail: command,
+    });
+  }
+
+  const canRunProbe =
+    checks.every((check) => check.code !== "grok_cwd_invalid" && check.code !== "grok_command_unresolvable");
+
+  const configuredModel = asString(config.model, DEFAULT_GROK_LOCAL_MODEL).trim();
+
+  if (canRunProbe) {
+    const modelsProbe = await runAdapterExecutionTargetProcess(
+      runId,
+      target,
+      command,
+      ["models"],
+      {
+        cwd,
+        env,
+        timeoutSec: Math.max(1, asNumber(config.helloProbeTimeoutSec, 45)),
+        graceSec: 5,
+        onLog: async () => {},
+      },
+    );
+
+    const probeOutput = `${modelsProbe.stdout}\n${modelsProbe.stderr}`;
+    const parsedModels = parseGrokModelsOutput(modelsProbe.stdout);
+    const authRequired = GROK_AUTH_REQUIRED_RE.test(probeOutput);
+
+    if (modelsProbe.timedOut) {
+      checks.push({
+        code: "grok_models_probe_timed_out",
+        level: "warn",
+        message: "`grok models` timed out.",
+        hint: "Retry the probe. If this persists, run `grok models` manually from the target environment.",
+      });
+    } else if ((modelsProbe.exitCode ?? 1) !== 0) {
+      checks.push({
+        code: authRequired ? "grok_auth_required" : "grok_models_probe_failed",
+        level: authRequired ? "warn" : "error",
+        message: authRequired
+          ? "Grok CLI is not authenticated."
+          : "`grok models` failed.",
+        detail: summarizeProbeDetail(modelsProbe.stdout, modelsProbe.stderr, null),
+        hint: authRequired ? "Run `grok login` on the target host, then retry." : undefined,
+      });
+    } else {
+      checks.push({
+        code: "grok_models_probe_passed",
+        level: "info",
+        message: parsedModels.authenticated
+          ? "Grok CLI authentication is configured."
+          : "`grok models` completed.",
+        detail: parsedModels.defaultModel ? `Default model: ${parsedModels.defaultModel}` : undefined,
+      });
+      if (parsedModels.models.length > 0) {
+        checks.push({
+          code: "grok_models_discovered",
+          level: "info",
+          message: `Discovered ${parsedModels.models.length} Grok model(s).`,
+        });
+      } else {
+        checks.push({
+          code: "grok_models_empty",
+          level: "warn",
+          message: "Grok returned no available models.",
+          hint: "Run `grok models` manually and verify the account has access to a model.",
+        });
+      }
+      if (configuredModel) {
+        checks.push({
+          code: parsedModels.models.includes(configuredModel) ? "grok_model_configured" : "grok_model_not_found",
+          level: parsedModels.models.includes(configuredModel) ? "info" : "warn",
+          message: parsedModels.models.includes(configuredModel)
+            ? `Configured model: ${configuredModel}`
+            : `Configured model "${configuredModel}" not found in available models.`,
+          hint: parsedModels.models.includes(configuredModel)
+            ? undefined
+            : "Run `grok models` and choose an available model id.",
+        });
+      }
+    }
+  }
+
+  if (canRunProbe) {
+    const probeArgs = [
+      "--output-format",
+      "streaming-json",
+      "--always-approve",
+      "--permission-mode",
+      "dontAsk",
+      "--disable-web-search",
+    ];
+    if (configuredModel && configuredModel !== DEFAULT_GROK_LOCAL_MODEL) {
+      probeArgs.push("--model", configuredModel);
+    }
+    probeArgs.push("--single", "Respond with exactly hello.");
+
+    const helloProbe = await runAdapterExecutionTargetProcess(
+      runId,
+      target,
+      command,
+      probeArgs,
+      {
+        cwd,
+        env,
+        timeoutSec: Math.max(1, asNumber(config.helloProbeTimeoutSec, 45)),
+        graceSec: 5,
+        onLog: async () => {},
+      },
+    );
+    const parsed = parseGrokJsonl(helloProbe.stdout);
+    const detail = summarizeProbeDetail(helloProbe.stdout, helloProbe.stderr, parsed.errorMessage);
+    const authRequired = GROK_AUTH_REQUIRED_RE.test(`${helloProbe.stdout}\n${helloProbe.stderr}`);
+
+    if (helloProbe.timedOut) {
+      checks.push({
+        code: "grok_hello_probe_timed_out",
+        level: "warn",
+        message: "Grok hello probe timed out.",
+        hint: "Retry the probe. If this persists, verify Grok can run a simple `--single` prompt manually.",
+      });
+    } else if ((helloProbe.exitCode ?? 1) !== 0) {
+      checks.push({
+        code: authRequired ? "grok_hello_probe_auth_required" : "grok_hello_probe_failed",
+        level: authRequired ? "warn" : "error",
+        message: authRequired
+          ? "Grok CLI could not answer the hello probe because authentication is missing."
+          : "Grok hello probe failed.",
+        ...(detail ? { detail } : {}),
+        hint: authRequired ? "Run `grok login` on the target host, then retry." : undefined,
+      });
+    } else if (/\bhello\b/i.test(parsed.summary)) {
+      checks.push({
+        code: "grok_hello_probe_passed",
+        level: "info",
+        message: "Grok hello probe succeeded.",
+      });
+    } else {
+      checks.push({
+        code: "grok_hello_probe_unexpected_output",
+        level: "warn",
+        message: "Grok hello probe succeeded but returned unexpected output.",
+        ...(detail ? { detail } : {}),
+      });
+    }
+  }
+
+  return {
+    adapterType: "grok_local",
+    status: summarizeStatus(checks),
+    checks,
+    testedAt: new Date().toISOString(),
+  };
+}

packages/adapters/grok-local/src/shared/turn-boundary.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { applyTurnBoundary, createTurnBoundaryState } from "./turn-boundary.js";
+
+function run(chunks: string[]): string {
+  const state = createTurnBoundaryState();
+  return chunks.map((chunk) => applyTurnBoundary(state, chunk)).join("");
+}
+
+describe("applyTurnBoundary", () => {
+  it("inserts a newline when a closing backtick is followed by a new capitalized turn", () => {
+    expect(run(["The user uses `", "ls", "`", "The", " `", "ls", "`", " returned"]))
+      .toBe("The user uses `ls`\nThe `ls` returned");
+  });
+
+  it("inserts a newline after sentence-ending punctuation glued to a capitalized word", () => {
+    expect(run(["returned", ":", "Confirmed", ":", " 4 files"]))
+      .toBe("returned:\nConfirmed: 4 files");
+  });
+
+  it("does not break apart backtick-wrapped CamelCase identifiers within a turn", () => {
+    expect(run(["render `", "React", "` then "]))
+      .toBe("render `React` then ");
+  });
+
+  it("leaves natural token streams with proper whitespace alone", () => {
+    expect(run(["The", " user", " wants", " me", " to", ":\n", "1", ".", " List"]))
+      .toBe("The user wants me to:\n1. List");
+  });
+
+  it("does not insert a separator when the next chunk starts with whitespace", () => {
+    expect(run(["function", ".", " They"]))
+      .toBe("function. They");
+  });
+
+  it("does not insert a separator when the next chunk starts lowercase", () => {
+    expect(run(["`", "ls", "`"]))
+      .toBe("`ls`");
+  });
+
+  it("does not insert a separator when the next chunk is a single character", () => {
+    expect(run([":", "A"]))
+      .toBe(":A");
+  });
+
+  it("does not insert a separator after a self-contained backtick span in a single chunk", () => {
+    // Greptile review: a chunk like "`ls`" is a balanced span; the following
+    // capitalized word should be treated as a continuation, not a new turn.
+    expect(run(["`ls`", "Then"]))
+      .toBe("`ls`Then");
+  });
+});

packages/adapters/grok-local/src/shared/turn-boundary.ts

@@ -0,0 +1,54 @@
+// Grok's `--output-format streaming-json` mode emits `thought` and `text` events
+// token-by-token. Between reasoning turns (around tool calls) it drops the `\n`
+// separator that the non-streaming `--output-format json` mode includes in the
+// aggregated `thought` field. This helper inserts a single `\n` when a new chunk
+// would otherwise glue two turns together (e.g. ``"`"`` then `"The"` => `` `The``).
+
+export interface TurnBoundaryState {
+  lastChunk: string;
+  backtickParity: 0 | 1;
+}
+
+export function createTurnBoundaryState(): TurnBoundaryState {
+  return { lastChunk: "", backtickParity: 0 };
+}
+
+function countBackticks(text: string): number {
+  let count = 0;
+  for (const ch of text) if (ch === "`") count += 1;
+  return count;
+}
+
+function endsWithSentenceClose(ch: string): boolean {
+  return ch === "." || ch === "?" || ch === "!" || ch === ":" || ch === ";";
+}
+
+export function applyTurnBoundary(state: TurnBoundaryState, incoming: string): string {
+  if (!incoming) return incoming;
+
+  let output = incoming;
+  const prev = state.lastChunk;
+  if (
+    prev &&
+    !/\s$/.test(prev) &&
+    !/^\s/.test(incoming) &&
+    /^[A-Z]/.test(incoming) &&
+    incoming.length >= 2
+  ) {
+    const lastChar = prev[prev.length - 1]!;
+    // Narrow the backtick trigger to a lone closing-backtick chunk (e.g. the
+    // stream "...`", "ls", "`" then "The"). A compound chunk like "`ls`" is a
+    // self-contained span and the following capitalized word is a continuation,
+    // not a new turn.
+    const closingLoneBacktick =
+      prev === "`" && state.backtickParity === 0;
+    const looksLikeNewTurn = endsWithSentenceClose(lastChar) || closingLoneBacktick;
+    if (looksLikeNewTurn) {
+      output = `\n${incoming}`;
+    }
+  }
+
+  state.lastChunk = incoming;
+  state.backtickParity = ((state.backtickParity + countBackticks(incoming)) % 2) as 0 | 1;
+  return output;
+}

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

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { buildGrokLocalConfig } from "./build-config.js";
+
+describe("buildGrokLocalConfig", () => {
+  it("maps create-form values into adapter config", () => {
+    expect(buildGrokLocalConfig({
+      cwd: "/tmp/project",
+      instructionsFilePath: "/tmp/AGENTS.md",
+      model: "grok-build",
+      thinkingEffort: "high",
+      envVars: "XAI_API_KEY=secret\n",
+      extraArgs: "--check, --verbatim",
+    } as never)).toEqual({
+      cwd: "/tmp/project",
+      instructionsFilePath: "/tmp/AGENTS.md",
+      model: "grok-build",
+      timeoutSec: 0,
+      graceSec: 20,
+      reasoningEffort: "high",
+      env: {
+        XAI_API_KEY: { type: "plain", value: "secret" },
+      },
+      extraArgs: ["--check", "--verbatim"],
+    });
+  });
+});

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

@@ -0,0 +1,74 @@
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+import { DEFAULT_GROK_LOCAL_MODEL } from "../index.js";
+
+function parseCommaArgs(value: string): string[] {
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseEnvVars(text: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    env[key] = value;
+  }
+  return env;
+}
+
+function parseEnvBindings(bindings: unknown): Record<string, unknown> {
+  if (typeof bindings !== "object" || bindings === null || Array.isArray(bindings)) return {};
+  const env: Record<string, unknown> = {};
+  for (const [key, raw] of Object.entries(bindings)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue;
+    if (typeof raw === "string") {
+      env[key] = { type: "plain", value: raw };
+      continue;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) continue;
+    const rec = raw as Record<string, unknown>;
+    if (rec.type === "plain" && typeof rec.value === "string") {
+      env[key] = { type: "plain", value: rec.value };
+      continue;
+    }
+    if (rec.type === "secret_ref" && typeof rec.secretId === "string") {
+      env[key] = {
+        type: "secret_ref",
+        secretId: rec.secretId,
+        ...(typeof rec.version === "number" || rec.version === "latest"
+          ? { version: rec.version }
+          : {}),
+      };
+    }
+  }
+  return env;
+}
+
+export function buildGrokLocalConfig(v: CreateConfigValues): Record<string, unknown> {
+  const ac: Record<string, unknown> = {};
+  if (v.cwd) ac.cwd = v.cwd;
+  if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
+  ac.model = v.model || DEFAULT_GROK_LOCAL_MODEL;
+  ac.timeoutSec = 0;
+  ac.graceSec = 20;
+  if (v.thinkingEffort) ac.reasoningEffort = v.thinkingEffort;
+  const env = parseEnvBindings(v.envBindings);
+  const legacy = parseEnvVars(v.envVars);
+  for (const [key, value] of Object.entries(legacy)) {
+    if (!Object.prototype.hasOwnProperty.call(env, key)) {
+      env[key] = { type: "plain", value };
+    }
+  }
+  if (Object.keys(env).length > 0) ac.env = env;
+
+  if (v.command) ac.command = v.command;
+  if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
+  return ac;
+}

packages/adapters/grok-local/src/ui/index.ts

@@ -0,0 +1,2 @@
+export { parseGrokStdoutLine, createGrokStdoutParser } from "./parse-stdout.js";
+export { buildGrokLocalConfig } from "./build-config.js";

packages/adapters/grok-local/src/ui/parse-stdout.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { createGrokStdoutParser, parseGrokStdoutLine } from "./parse-stdout.js";
+
+describe("parseGrokStdoutLine", () => {
+  const ts = "2026-05-15T00:00:00.000Z";
+
+  it("maps thought/text/end events into transcript entries", () => {
+    expect(parseGrokStdoutLine(JSON.stringify({ type: "thought", data: "Plan first." }), ts)).toEqual([
+      { kind: "thinking", ts, text: "Plan first.", delta: true },
+    ]);
+    expect(parseGrokStdoutLine(JSON.stringify({ type: "text", data: "hello" }), ts)).toEqual([
+      { kind: "assistant", ts, text: "hello", delta: true },
+    ]);
+    expect(parseGrokStdoutLine(JSON.stringify({ type: "end", stopReason: "EndTurn", sessionId: "sess-1" }), ts)).toEqual([
+      { kind: "system", ts, text: "stop_reason=EndTurn session=sess-1" },
+    ]);
+  });
+
+  it("surfaces structured Grok error payload text", () => {
+    expect(parseGrokStdoutLine(JSON.stringify({
+      type: "error",
+      error: { message: "Authentication required" },
+    }), ts)).toEqual([
+      { kind: "stderr", ts, text: "Authentication required" },
+    ]);
+  });
+});
+
+describe("createGrokStdoutParser", () => {
+  const ts = "2026-05-15T00:00:00.000Z";
+
+  function thoughtTexts(chunks: string[]): string {
+    const parser = createGrokStdoutParser();
+    return chunks
+      .map((data) => parser.parseLine(JSON.stringify({ type: "thought", data }), ts))
+      .flat()
+      .map((entry) => entry.kind === "thinking" ? entry.text : "")
+      .join("");
+  }
+
+  it("inserts a newline between reasoning turns that grok streaming-json glues together", () => {
+    // Reproduces PAPA-349: token stream "...using `ls`" then a new turn "The `ls` command returned"
+    expect(thoughtTexts(["The user uses `", "ls", "`", "The", " `", "ls", "`", " returned"]))
+      .toBe("The user uses `ls`\nThe `ls` returned");
+  });
+
+  it("inserts a newline when a turn ends with a colon and the next turn starts capitalized", () => {
+    expect(thoughtTexts(["returned", ":", "Confirmed", ":", " 4 files"]))
+      .toBe("returned:\nConfirmed: 4 files");
+  });
+
+  it("resets state between independent transcript builds", () => {
+    const parser = createGrokStdoutParser();
+    parser.parseLine(JSON.stringify({ type: "thought", data: "first:" }), ts);
+    parser.reset();
+    expect(parser.parseLine(JSON.stringify({ type: "thought", data: "Second" }), ts)).toEqual([
+      { kind: "thinking", ts, text: "Second", delta: true },
+    ]);
+  });
+
+  it("does not modify assistant `text` chunks", () => {
+    // PAPA-349 review feedback: keep final assistant text streaming verbatim;
+    // the boundary heuristic is scoped to reasoning.
+    const parser = createGrokStdoutParser();
+    parser.parseLine(JSON.stringify({ type: "text", data: "Done." }), ts);
+    expect(parser.parseLine(JSON.stringify({ type: "text", data: "Next" }), ts)).toEqual([
+      { kind: "assistant", ts, text: "Next", delta: true },
+    ]);
+  });
+});

packages/adapters/grok-local/src/ui/parse-stdout.ts

@@ -0,0 +1,87 @@
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+import { applyTurnBoundary, createTurnBoundaryState, type TurnBoundaryState } from "../shared/turn-boundary.js";
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown, fallback = ""): string {
+  return typeof value === "string" ? value : fallback;
+}
+
+function extractErrorText(value: unknown): string {
+  if (typeof value === "string") return value;
+  const record = asRecord(value);
+  if (!record) return "";
+  return asString(record.message) || asString(record.detail) || asString(record.code);
+}
+
+function parseLineInternal(
+  line: string,
+  ts: string,
+  thoughtBoundary: TurnBoundaryState,
+): TranscriptEntry[] {
+  const parsed = asRecord(safeJsonParse(line));
+  if (!parsed) {
+    return [{ kind: "stdout", ts, text: line }];
+  }
+
+  const type = asString(parsed.type).trim();
+
+  if (type === "thought") {
+    const text = asString(parsed.data);
+    if (!text) return [];
+    return [{ kind: "thinking", ts, text: applyTurnBoundary(thoughtBoundary, text), delta: true }];
+  }
+
+  if (type === "text") {
+    const text = asString(parsed.data);
+    if (!text) return [];
+    return [{ kind: "assistant", ts, text, delta: true }];
+  }
+
+  if (type === "error") {
+    const text = asString(parsed.data) || asString(parsed.message) || extractErrorText(parsed.error);
+    return text ? [{ kind: "stderr", ts, text }] : [{ kind: "stderr", ts, text: "Grok error" }];
+  }
+
+  if (type === "end") {
+    const stopReason = asString(parsed.stopReason).trim();
+    const sessionId = asString(parsed.sessionId).trim();
+    const parts = [
+      stopReason ? `stop_reason=${stopReason}` : "",
+      sessionId ? `session=${sessionId}` : "",
+    ].filter(Boolean);
+    return [{ kind: "system", ts, text: parts.join(" ") || "run completed" }];
+  }
+
+  return [{ kind: "system", ts, text: `event: ${type || "unknown"}` }];
+}
+
+export function createGrokStdoutParser() {
+  let thoughtBoundary = createTurnBoundaryState();
+  return {
+    parseLine(line: string, ts: string): TranscriptEntry[] {
+      return parseLineInternal(line, ts, thoughtBoundary);
+    },
+    reset() {
+      thoughtBoundary = createTurnBoundaryState();
+    },
+  };
+}
+
+// Stateless fallback for callers that haven't migrated to the stateful factory.
+// Without state, consecutive thought chunks at reasoning-turn boundaries can
+// still appear merged; prefer createGrokStdoutParser for live transcripts.
+export function parseGrokStdoutLine(line: string, ts: string): TranscriptEntry[] {
+  return parseLineInternal(line, ts, createTurnBoundaryState());
+}

packages/adapters/grok-local/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

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

@@ -9,6 +9,7 @@ import type {
 import type { AdapterExecutionTarget } from "@paperclipai/adapter-utils/execution-target";
 import {
   asBoolean,
+  asNumber,
   asString,
   asStringArray,
   parseObject,
@@ -72,6 +73,7 @@ export async function testEnvironment(
   const command = asString(config.command, "opencode");
   const target = ctx.executionTarget ?? null;
   const targetIsRemote = target?.kind === "remote";
+  const targetIsSandbox = target?.kind === "remote" && target.transport === "sandbox";
   const cwd = resolveAdapterExecutionTargetCwd(target, asString(config.cwd, ""), process.cwd());
   const targetLabel = targetIsRemote
     ? ctx.environmentName ?? describeAdapterExecutionTarget(target)
@@ -334,6 +336,14 @@ export async function testEnvironment(
       if (variant) args.push("--variant", variant);
       if (extraArgs.length > 0) args.push(...extraArgs);
 
+      // Sandbox bridges still add cold-start and transport overhead, but the
+      // standard-2 Cloudflare tier now probes quickly enough that 90s keeps
+      // useful headroom without letting slow hangs linger.
+      const helloProbeTimeoutSec = Math.max(
+        1,
+        asNumber(config.helloProbeTimeoutSec, targetIsSandbox ? 90 : 60),
+      );
+
       try {
         const probe = await runAdapterExecutionTargetProcess(
           runId,
@@ -343,7 +353,7 @@ export async function testEnvironment(
           {
             cwd: runtimeCwd,
             env: runtimeEnv,
-            timeoutSec: 60,
+            timeoutSec: helloProbeTimeoutSec,
             graceSec: 5,
             stdin: "Respond with hello.",
             onLog: async () => {},

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

@@ -3,7 +3,7 @@ import type { AdapterModelProfileDefinition } from "@paperclipai/adapter-utils";
 export const type = "pi_local";
 export const label = "Pi (local)";
 
-export const SANDBOX_INSTALL_COMMAND = "npm install -g @mariozechner/pi-coding-agent";
+export const SANDBOX_INSTALL_COMMAND = "npm install -g @earendil-works/pi-coding-agent@0.74.0";
 
 export const models: Array<{ id: string; label: string }> = [];
 

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

@@ -309,6 +309,107 @@ describeEmbeddedPostgres("runDatabaseBackup", () => {
     60_000,
   );
 
+  it(
+    "preserves composite foreign key column order without duplicate referenced columns",
+    async () => {
+      const sourceConnectionString = await createTempDatabase();
+      const restoreConnectionString = await createSiblingDatabase(
+        sourceConnectionString,
+        "paperclip_composite_fk_restore_target",
+      );
+      const backupDir = createTempDir("paperclip-db-composite-fk-backup-");
+      const sourceSql = postgres(sourceConnectionString, { max: 1, onnotice: () => {} });
+      const restoreSql = postgres(restoreConnectionString, { max: 1, onnotice: () => {} });
+
+      try {
+        await sourceSql.unsafe(`
+          CREATE SCHEMA "plugin_composite_fk";
+          CREATE TABLE "plugin_composite_fk"."content_cases" (
+            "id" uuid PRIMARY KEY,
+            "company_id" uuid NOT NULL,
+            "title" text NOT NULL,
+            CONSTRAINT "content_cases_company_case_unique" UNIQUE ("company_id", "id")
+          );
+          CREATE TABLE "plugin_composite_fk"."content_case_signals" (
+            "company_id" uuid NOT NULL,
+            "case_id" uuid NOT NULL,
+            "signal" text NOT NULL,
+            "scopes" text[] NOT NULL,
+            "warnings" jsonb DEFAULT '[]'::jsonb NOT NULL,
+            CONSTRAINT "content_case_signals_company_case"
+              FOREIGN KEY ("company_id", "case_id")
+              REFERENCES "plugin_composite_fk"."content_cases" ("company_id", "id")
+              ON DELETE CASCADE
+          );
+          INSERT INTO "plugin_composite_fk"."content_cases" ("company_id", "id", "title")
+          VALUES (
+            '11111111-1111-4111-8111-111111111111',
+            '22222222-2222-4222-8222-222222222222',
+            'case'
+          );
+          INSERT INTO "plugin_composite_fk"."content_case_signals" ("company_id", "case_id", "signal", "scopes", "warnings")
+          VALUES (
+            '11111111-1111-4111-8111-111111111111',
+            '22222222-2222-4222-8222-222222222222',
+            'signal',
+            ARRAY['upstream_import:preview', 'scope with space', 'quoted "scope"', 'NULL', 'null'],
+            jsonb_build_array('json warning', jsonb_build_object('code', 'quoted "value"'))
+          );
+        `);
+
+        const result = await runDatabaseBackup({
+          connectionString: sourceConnectionString,
+          backupDir,
+          retention: { dailyDays: 7, weeklyWeeks: 4, monthlyMonths: 1 },
+          filenamePrefix: "paperclip-composite-fk-test",
+          backupEngine: "javascript",
+        });
+
+        await runDatabaseRestore({
+          connectionString: restoreConnectionString,
+          backupFile: result.backupFile,
+        });
+
+        const rows = await restoreSql.unsafe<{
+          signal: string;
+          title: string;
+          scopes: string[];
+          warnings: Array<string | { code: string }>;
+        }[]>(`
+          SELECT s."signal", c."title", s."scopes", s."warnings"
+          FROM "plugin_composite_fk"."content_case_signals" s
+          JOIN "plugin_composite_fk"."content_cases" c
+            ON c."company_id" = s."company_id"
+           AND c."id" = s."case_id"
+        `);
+        expect(rows).toEqual([
+          {
+            signal: "signal",
+            title: "case",
+            scopes: ["upstream_import:preview", "scope with space", 'quoted "scope"', "NULL", "null"],
+            warnings: ["json warning", { code: 'quoted "value"' }],
+          },
+        ]);
+
+        await expect(
+          restoreSql.unsafe(`
+            INSERT INTO "plugin_composite_fk"."content_case_signals" ("company_id", "case_id", "signal", "scopes")
+            VALUES (
+              '11111111-1111-4111-8111-111111111111',
+              '33333333-3333-4333-8333-333333333333',
+              'orphan',
+              ARRAY[]::text[]
+            )
+          `),
+        ).rejects.toThrow();
+      } finally {
+        await sourceSql.end();
+        await restoreSql.end();
+      }
+    },
+    60_000,
+  );
+
   it(
     "restores legacy public-only backups without migration history",
     async () => {

packages/db/src/backup-lib.ts

@@ -249,12 +249,39 @@ function hasBackupTransforms(opts: RunDatabaseBackupOptions): boolean {
     Object.keys(opts.nullifyColumns ?? {}).length > 0;
 }
 
-function formatSqlValue(rawValue: unknown, columnName: string | undefined, nullifiedColumns: Set<string>): string {
+function formatPostgresArrayElement(value: unknown): string {
+  if (value === null || value === undefined) return "NULL";
+  if (Array.isArray(value)) return formatPostgresArrayLiteral(value);
+  const raw = value instanceof Date
+    ? value.toISOString()
+    : typeof value === "object"
+      ? JSON.stringify(value)
+      : String(value);
+  if (raw.length === 0 || /^null$/i.test(raw) || /[{}\s,"\\]/.test(raw)) {
+    return `"${raw.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+  }
+  return raw;
+}
+
+function formatPostgresArrayLiteral(value: unknown[]): string {
+  return `{${value.map(formatPostgresArrayElement).join(",")}}`;
+}
+
+function formatSqlValue(
+  rawValue: unknown,
+  columnName: string | undefined,
+  nullifiedColumns: Set<string>,
+  dataType?: string,
+): string {
   const val = columnName && nullifiedColumns.has(columnName) ? null : rawValue;
   if (val === null || val === undefined) return "NULL";
+  if (dataType === "json" || dataType === "jsonb") {
+    return formatSqlLiteral(JSON.stringify(val));
+  }
   if (typeof val === "boolean") return val ? "true" : "false";
   if (typeof val === "number") return String(val);
   if (val instanceof Date) return formatSqlLiteral(val.toISOString());
+  if (Array.isArray(val)) return formatSqlLiteral(formatPostgresArrayLiteral(val));
   if (typeof val === "object") return formatSqlLiteral(JSON.stringify(val));
   return formatSqlLiteral(String(val));
 }
@@ -745,58 +772,7 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
       emit("");
     }
 
-    // Foreign keys (after all tables created)
-    const allForeignKeys = await sql<{
-      constraint_name: string;
-      source_schema: string;
-      source_table: string;
-      source_columns: string[];
-      target_schema: string;
-      target_table: string;
-      target_columns: string[];
-      update_rule: string;
-      delete_rule: string;
-    }[]>`
-      SELECT
-        c.conname AS constraint_name,
-        srcn.nspname AS source_schema,
-        src.relname AS source_table,
-        array_agg(sa.attname ORDER BY array_position(c.conkey, sa.attnum)) AS source_columns,
-        tgtn.nspname AS target_schema,
-        tgt.relname AS target_table,
-        array_agg(ta.attname ORDER BY array_position(c.confkey, ta.attnum)) AS target_columns,
-        CASE c.confupdtype WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' END AS update_rule,
-        CASE c.confdeltype WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' END AS delete_rule
-      FROM pg_constraint c
-      JOIN pg_class src ON src.oid = c.conrelid
-      JOIN pg_namespace srcn ON srcn.oid = src.relnamespace
-      JOIN pg_class tgt ON tgt.oid = c.confrelid
-      JOIN pg_namespace tgtn ON tgtn.oid = tgt.relnamespace
-      JOIN pg_attribute sa ON sa.attrelid = src.oid AND sa.attnum = ANY(c.conkey)
-      JOIN pg_attribute ta ON ta.attrelid = tgt.oid AND ta.attnum = ANY(c.confkey)
-      WHERE c.contype = 'f'
-        AND ${sql.unsafe(nonSystemSchemaPredicate("srcn.nspname"))}
-      GROUP BY c.conname, srcn.nspname, src.relname, tgtn.nspname, tgt.relname, c.confupdtype, c.confdeltype
-      ORDER BY srcn.nspname, src.relname, c.conname
-    `;
-    const fks = allForeignKeys.filter(
-      (fk) => includedTableNames.has(tableKey(fk.source_schema, fk.source_table))
-        && includedTableNames.has(tableKey(fk.target_schema, fk.target_table)),
-    );
-
-    if (fks.length > 0) {
-      emit("-- Foreign keys");
-      for (const fk of fks) {
-        const srcCols = fk.source_columns.map((c) => `"${c}"`).join(", ");
-        const tgtCols = fk.target_columns.map((c) => `"${c}"`).join(", ");
-        emitStatement(
-          `ALTER TABLE ${quoteQualifiedName(fk.source_schema, fk.source_table)} ADD CONSTRAINT "${fk.constraint_name}" FOREIGN KEY (${srcCols}) REFERENCES ${quoteQualifiedName(fk.target_schema, fk.target_table)} (${tgtCols}) ON UPDATE ${fk.update_rule} ON DELETE ${fk.delete_rule};`,
-        );
-      }
-      emit("");
-    }
-
-    // Unique constraints
+    // Unique constraints must exist before foreign keys that reference them.
     const allUniqueConstraints = await sql<{
       constraint_name: string;
       schema_name: string;
@@ -827,6 +803,58 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
       emit("");
     }
 
+    // Foreign keys (after all tables and referenced unique constraints are created)
+    const allForeignKeys = await sql<{
+      constraint_name: string;
+      source_schema: string;
+      source_table: string;
+      source_columns: string[];
+      target_schema: string;
+      target_table: string;
+      target_columns: string[];
+      update_rule: string;
+      delete_rule: string;
+    }[]>`
+      SELECT
+        c.conname AS constraint_name,
+        srcn.nspname AS source_schema,
+        src.relname AS source_table,
+        array_agg(sa.attname ORDER BY key_columns.ordinal_position) AS source_columns,
+        tgtn.nspname AS target_schema,
+        tgt.relname AS target_table,
+        array_agg(ta.attname ORDER BY key_columns.ordinal_position) AS target_columns,
+        CASE c.confupdtype WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' END AS update_rule,
+        CASE c.confdeltype WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' END AS delete_rule
+      FROM pg_constraint c
+      JOIN pg_class src ON src.oid = c.conrelid
+      JOIN pg_namespace srcn ON srcn.oid = src.relnamespace
+      JOIN pg_class tgt ON tgt.oid = c.confrelid
+      JOIN pg_namespace tgtn ON tgtn.oid = tgt.relnamespace
+      JOIN LATERAL unnest(c.conkey, c.confkey) WITH ORDINALITY AS key_columns(source_attnum, target_attnum, ordinal_position) ON true
+      JOIN pg_attribute sa ON sa.attrelid = src.oid AND sa.attnum = key_columns.source_attnum
+      JOIN pg_attribute ta ON ta.attrelid = tgt.oid AND ta.attnum = key_columns.target_attnum
+      WHERE c.contype = 'f'
+        AND ${sql.unsafe(nonSystemSchemaPredicate("srcn.nspname"))}
+      GROUP BY c.conname, srcn.nspname, src.relname, tgtn.nspname, tgt.relname, c.confupdtype, c.confdeltype
+      ORDER BY srcn.nspname, src.relname, c.conname
+    `;
+    const fks = allForeignKeys.filter(
+      (fk) => includedTableNames.has(tableKey(fk.source_schema, fk.source_table))
+        && includedTableNames.has(tableKey(fk.target_schema, fk.target_table)),
+    );
+
+    if (fks.length > 0) {
+      emit("-- Foreign keys");
+      for (const fk of fks) {
+        const srcCols = fk.source_columns.map((c) => `"${c}"`).join(", ");
+        const tgtCols = fk.target_columns.map((c) => `"${c}"`).join(", ");
+        emitStatement(
+          `ALTER TABLE ${quoteQualifiedName(fk.source_schema, fk.source_table)} ADD CONSTRAINT "${fk.constraint_name}" FOREIGN KEY (${srcCols}) REFERENCES ${quoteQualifiedName(fk.target_schema, fk.target_table)} (${tgtCols}) ON UPDATE ${fk.update_rule} ON DELETE ${fk.delete_rule};`,
+        );
+      }
+      emit("");
+    }
+
     // Indexes (non-primary, non-unique-constraint)
     const allIndexes = await sql<{ schema_name: string; tablename: string; indexdef: string }[]>`
       SELECT schemaname AS schema_name, tablename, indexdef
@@ -895,7 +923,7 @@ export async function runDatabaseBackup(opts: RunDatabaseBackupOptions): Promise
       for await (const rows of rowCursor) {
         for (const row of rows) {
           const values = row.map((rawValue, index) =>
-            formatSqlValue(rawValue, cols[index]?.column_name, nullifiedColumns),
+            formatSqlValue(rawValue, cols[index]?.column_name, nullifiedColumns, cols[index]?.data_type),
           );
           emitStatement(`INSERT INTO ${qualifiedTableName} (${colNames}) VALUES (${values.join(", ")});`);
         }

packages/db/src/embedded-postgres-native.test.ts

@@ -0,0 +1,43 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ensureLinuxSharedLibraryAliases } from "./embedded-postgres-native.js";
+
+describe("embedded Postgres native runtime", () => {
+  const tempDirs: string[] = [];
+
+  afterEach(() => {
+    for (const tempDir of tempDirs.splice(0)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it.runIf(process.platform !== "win32")("creates soname aliases for bundled patch-level shared libraries", async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-embedded-pg-libs-"));
+    tempDirs.push(tempDir);
+    fs.writeFileSync(path.join(tempDir, "libicuuc.so.60.2"), "");
+    fs.writeFileSync(path.join(tempDir, "libicui18n.so.60.2"), "");
+    fs.writeFileSync(path.join(tempDir, "README.md"), "");
+
+    const created = await ensureLinuxSharedLibraryAliases(tempDir);
+
+    expect(created.map((file) => path.basename(file)).sort()).toEqual([
+      "libicui18n.so.60",
+      "libicuuc.so.60",
+    ]);
+    expect(fs.readlinkSync(path.join(tempDir, "libicuuc.so.60"))).toBe("libicuuc.so.60.2");
+  });
+
+  it.runIf(process.platform !== "win32")("is idempotent when aliases already exist", async () => {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-embedded-pg-libs-"));
+    tempDirs.push(tempDir);
+    fs.writeFileSync(path.join(tempDir, "libicuuc.so.60.2"), "");
+
+    await ensureLinuxSharedLibraryAliases(tempDir);
+    const second = await ensureLinuxSharedLibraryAliases(tempDir);
+
+    expect(second).toEqual([]);
+    expect(fs.readlinkSync(path.join(tempDir, "libicuuc.so.60"))).toBe("libicuuc.so.60.2");
+  });
+});

packages/db/src/embedded-postgres-native.ts

@@ -0,0 +1,85 @@
+import { promises as fs } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const require = createRequire(import.meta.url);
+
+function resolveNativePackageName(): string | null {
+  if (process.platform !== "linux") return null;
+
+  switch (process.arch) {
+    case "arm64":
+      return "linux-arm64";
+    case "arm":
+      return "linux-arm";
+    case "ia32":
+      return "linux-ia32";
+    case "ppc64":
+      return "linux-ppc64";
+    case "x64":
+      return "linux-x64";
+    default:
+      return null;
+  }
+}
+
+async function pathExists(value: string): Promise<boolean> {
+  try {
+    await fs.stat(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveEmbeddedPostgresPackageRoot(): string | null {
+  try {
+    const entry = require.resolve("embedded-postgres");
+    return path.dirname(path.dirname(entry));
+  } catch {
+    return null;
+  }
+}
+
+function prependPathEnv(name: string, value: string): void {
+  const current = process.env[name] ?? "";
+  const parts = current.split(path.delimiter).filter(Boolean);
+  if (parts.includes(value)) return;
+  process.env[name] = [value, ...parts].join(path.delimiter);
+}
+
+export async function ensureLinuxSharedLibraryAliases(libDir: string): Promise<string[]> {
+  const entries = await fs.readdir(libDir, { withFileTypes: true });
+  const created: string[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const match = entry.name.match(/^(lib.+\.so\.\d+)\.\d+(?:\.\d+)?$/);
+    if (!match) continue;
+
+    const aliasName = match[1];
+    const aliasPath = path.join(libDir, aliasName);
+    try {
+      await fs.symlink(entry.name, aliasPath);
+      created.push(aliasPath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
+      throw error;
+    }
+  }
+
+  return created;
+}
+
+export async function prepareEmbeddedPostgresNativeRuntime(): Promise<void> {
+  const nativePackageName = resolveNativePackageName();
+  const packageRoot = resolveEmbeddedPostgresPackageRoot();
+  if (!nativePackageName || !packageRoot) return;
+
+  const nativeRoot = path.resolve(packageRoot, "..", "@embedded-postgres", nativePackageName);
+  const libDir = path.join(nativeRoot, "native", "lib");
+  if (!(await pathExists(libDir))) return;
+
+  prependPathEnv("LD_LIBRARY_PATH", libDir);
+  await ensureLinuxSharedLibraryAliases(libDir);
+}

packages/db/src/index.ts

@@ -30,6 +30,10 @@ export {
   createEmbeddedPostgresLogBuffer,
   formatEmbeddedPostgresError,
 } from "./embedded-postgres-error.js";
+export {
+  ensureLinuxSharedLibraryAliases,
+  prepareEmbeddedPostgresNativeRuntime,
+} from "./embedded-postgres-native.js";
 export { issueRelations } from "./schema/issue_relations.js";
 export { issueReferenceMentions } from "./schema/issue_reference_mentions.js";
 export * from "./schema/index.js";

packages/db/src/migration-runtime.ts

@@ -3,6 +3,7 @@ import { createServer } from "node:net";
 import path from "node:path";
 import { ensurePostgresDatabase, getPostgresDataDirectory } from "./client.js";
 import { createEmbeddedPostgresLogBuffer, formatEmbeddedPostgresError } from "./embedded-postgres-error.js";
+import { prepareEmbeddedPostgresNativeRuntime } from "./embedded-postgres-native.js";
 import { resolveDatabaseTarget } from "./runtime-config.js";
 
 type EmbeddedPostgresInstance = {
@@ -92,6 +93,7 @@ async function ensureEmbeddedPostgresConnection(
   preferredPort: number,
 ): Promise<MigrationConnection> {
   const EmbeddedPostgres = await loadEmbeddedPostgresCtor();
+  await prepareEmbeddedPostgresNativeRuntime();
   const selectedPort = await findAvailablePort(preferredPort);
   const postmasterPidFile = path.resolve(dataDir, "postmaster.pid");
   const pgVersionFile = path.resolve(dataDir, "PG_VERSION");

packages/db/src/migrations/0085_tranquil_the_executioner.sql

@@ -0,0 +1,8 @@
+ALTER TABLE "documents" ADD COLUMN IF NOT EXISTS "locked_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "documents" ADD COLUMN IF NOT EXISTS "locked_by_agent_id" uuid;--> statement-breakpoint
+ALTER TABLE "documents" ADD COLUMN IF NOT EXISTS "locked_by_user_id" text;--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'documents_locked_by_agent_id_agents_id_fk') THEN
+		ALTER TABLE "documents" ADD CONSTRAINT "documents_locked_by_agent_id_agents_id_fk" FOREIGN KEY ("locked_by_agent_id") REFERENCES "public"."agents"("id") ON DELETE set null ON UPDATE no action;
+	END IF;
+END $$;

packages/db/src/migrations/0086_routine_env_runtime_contract.sql

@@ -0,0 +1,8 @@
+ALTER TABLE "routines" ADD COLUMN IF NOT EXISTS "env" jsonb;--> statement-breakpoint
+ALTER TABLE "routine_runs" ADD COLUMN IF NOT EXISTS "routine_revision_id" uuid;--> statement-breakpoint
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'routine_runs_routine_revision_id_routine_revisions_id_fk') THEN
+    ALTER TABLE "routine_runs" ADD CONSTRAINT "routine_runs_routine_revision_id_routine_revisions_id_fk" FOREIGN KEY ("routine_revision_id") REFERENCES "public"."routine_revisions"("id") ON DELETE set null ON UPDATE no action;
+  END IF;
+END $$;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "routine_runs_revision_idx" ON "routine_runs" USING btree ("routine_revision_id");

packages/db/src/migrations/0087_backfill_environment_manage_human_defaults.sql

@@ -0,0 +1,29 @@
+INSERT INTO "principal_permission_grants" (
+  "company_id",
+  "principal_type",
+  "principal_id",
+  "permission_key",
+  "scope",
+  "granted_by_user_id",
+  "created_at",
+  "updated_at"
+)
+SELECT
+  "company_id",
+  'user',
+  "principal_id",
+  'environments:manage',
+  NULL,
+  NULL,
+  now(),
+  now()
+FROM "company_memberships"
+WHERE "principal_type" = 'user'
+  AND "status" = 'active'
+  AND "membership_role" IN ('owner', 'admin')
+ON CONFLICT (
+  "company_id",
+  "principal_type",
+  "principal_id",
+  "permission_key"
+) DO NOTHING;

packages/db/src/migrations/0088_backfill_principal_access_compatibility.sql

@@ -0,0 +1,75 @@
+INSERT INTO "company_memberships" (
+  "company_id",
+  "principal_type",
+  "principal_id",
+  "status",
+  "membership_role",
+  "created_at",
+  "updated_at"
+)
+SELECT
+  "company_id",
+  'agent',
+  "id",
+  'active',
+  'member',
+  now(),
+  now()
+FROM "agents"
+WHERE "status" NOT IN ('pending_approval', 'terminated')
+ON CONFLICT (
+  "company_id",
+  "principal_type",
+  "principal_id"
+) DO NOTHING;
+
+INSERT INTO "principal_permission_grants" (
+  "company_id",
+  "principal_type",
+  "principal_id",
+  "permission_key",
+  "scope",
+  "granted_by_user_id",
+  "created_at",
+  "updated_at"
+)
+SELECT
+  memberships."company_id",
+  'user',
+  memberships."principal_id",
+  role_defaults."permission_key",
+  NULL,
+  NULL,
+  now(),
+  now()
+FROM "company_memberships" memberships
+JOIN (
+  VALUES
+    ('owner', 'agents:create'),
+    ('owner', 'environments:manage'),
+    ('owner', 'users:invite'),
+    ('owner', 'users:manage_permissions'),
+    ('owner', 'tasks:assign'),
+    ('owner', 'joins:approve'),
+    ('admin', 'agents:create'),
+    ('admin', 'environments:manage'),
+    ('admin', 'users:invite'),
+    ('admin', 'tasks:assign'),
+    ('admin', 'joins:approve'),
+    ('operator', 'tasks:assign')
+) AS role_defaults("membership_role", "permission_key")
+  ON role_defaults."membership_role" = CASE
+    WHEN memberships."membership_role" = 'owner' THEN 'owner'
+    WHEN memberships."membership_role" = 'admin' THEN 'admin'
+    WHEN memberships."membership_role" = 'viewer' THEN 'viewer'
+    WHEN memberships."membership_role" = 'member' THEN 'operator'
+    ELSE 'operator'
+  END
+WHERE memberships."principal_type" = 'user'
+  AND memberships."status" = 'active'
+ON CONFLICT (
+  "company_id",
+  "principal_type",
+  "principal_id",
+  "permission_key"
+) DO NOTHING;

packages/db/src/migrations/0089_cloud_upstreams.sql

@@ -0,0 +1,71 @@
+CREATE TABLE IF NOT EXISTS "cloud_upstream_connections" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "company_id" uuid NOT NULL,
+  "remote_url" text NOT NULL,
+  "source_instance_id" text NOT NULL,
+  "source_instance_fingerprint" text NOT NULL,
+  "source_public_key" text NOT NULL,
+  "private_key_pem" text NOT NULL,
+  "token_status" text NOT NULL,
+  "scopes" text[] DEFAULT '{}' NOT NULL,
+  "authorized_global_user_id" text,
+  "access_token" text,
+  "token_id" text,
+  "token_expires_at" timestamp with time zone,
+  "target_stack_id" text NOT NULL,
+  "target_stack_slug" text,
+  "target_stack_display_name" text,
+  "target_company_id" text NOT NULL,
+  "target_origin" text NOT NULL,
+  "target_primary_host" text NOT NULL,
+  "target_product" text NOT NULL,
+  "target_schema_major" integer NOT NULL,
+  "target_max_chunk_bytes" integer NOT NULL,
+  "pending_state" text,
+  "pending_code_verifier" text,
+  "pending_redirect_uri" text,
+  "pending_token_url" text,
+  "last_run_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 "cloud_upstream_runs" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "connection_id" uuid NOT NULL,
+  "company_id" uuid NOT NULL,
+  "remote_run_id" text,
+  "status" text NOT NULL,
+  "active_step" text NOT NULL,
+  "progress_percent" integer DEFAULT 0 NOT NULL,
+  "dry_run" boolean DEFAULT false NOT NULL,
+  "retry_of_run_id" uuid,
+  "summary" jsonb DEFAULT '[]'::jsonb NOT NULL,
+  "warnings" jsonb DEFAULT '[]'::jsonb NOT NULL,
+  "conflicts" jsonb DEFAULT '[]'::jsonb NOT NULL,
+  "events" jsonb DEFAULT '[]'::jsonb NOT NULL,
+  "report" jsonb DEFAULT '{}'::jsonb NOT NULL,
+  "idempotency_key" text NOT NULL,
+  "manifest_hash" text NOT NULL,
+  "target_url" text,
+  "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "completed_at" timestamp with time zone
+);--> statement-breakpoint
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'cloud_upstream_connections_company_id_companies_id_fk') THEN
+    ALTER TABLE "cloud_upstream_connections" ADD CONSTRAINT "cloud_upstream_connections_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+  END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'cloud_upstream_runs_connection_id_cloud_upstream_connections_id_fk') THEN
+    ALTER TABLE "cloud_upstream_runs" ADD CONSTRAINT "cloud_upstream_runs_connection_id_cloud_upstream_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."cloud_upstream_connections"("id") ON DELETE cascade ON UPDATE no action;
+  END IF;
+END $$;--> statement-breakpoint
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'cloud_upstream_runs_company_id_companies_id_fk') THEN
+    ALTER TABLE "cloud_upstream_runs" ADD CONSTRAINT "cloud_upstream_runs_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+  END IF;
+END $$;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "cloud_upstream_connections_company_idx" ON "cloud_upstream_connections" USING btree ("company_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "cloud_upstream_runs_company_created_idx" ON "cloud_upstream_runs" USING btree ("company_id","created_at");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "cloud_upstream_runs_connection_idx" ON "cloud_upstream_runs" USING btree ("connection_id");

packages/db/src/migrations/0090_resource_memberships.sql

@@ -0,0 +1,55 @@
+CREATE TABLE IF NOT EXISTS "agent_memberships" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"user_id" text NOT NULL,
+	"state" text DEFAULT 'joined' 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 "project_memberships" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid NOT NULL,
+	"user_id" text NOT NULL,
+	"state" text DEFAULT 'joined' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agent_memberships_company_id_companies_id_fk') THEN
+		ALTER TABLE "agent_memberships" ADD CONSTRAINT "agent_memberships_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agent_memberships_agent_id_agents_id_fk') THEN
+		ALTER TABLE "agent_memberships" ADD CONSTRAINT "agent_memberships_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'project_memberships_company_id_companies_id_fk') THEN
+		ALTER TABLE "project_memberships" ADD CONSTRAINT "project_memberships_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'project_memberships_project_id_projects_id_fk') THEN
+		ALTER TABLE "project_memberships" ADD CONSTRAINT "project_memberships_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "agent_memberships_company_user_idx" ON "agent_memberships" USING btree ("company_id","user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "agent_memberships_agent_idx" ON "agent_memberships" USING btree ("agent_id");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "agent_memberships_company_user_agent_uq" ON "agent_memberships" USING btree ("company_id","user_id","agent_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "project_memberships_company_user_idx" ON "project_memberships" USING btree ("company_id","user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "project_memberships_project_idx" ON "project_memberships" USING btree ("project_id");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "project_memberships_company_user_project_uq" ON "project_memberships" USING btree ("company_id","user_id","project_id");

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

@@ -596,6 +596,48 @@
       "when": 1778355326070,
       "tag": "0084_issue_recovery_actions",
       "breakpoints": true
+    },
+    {
+      "idx": 85,
+      "version": "7",
+      "when": 1778787362162,
+      "tag": "0085_tranquil_the_executioner",
+      "breakpoints": true
+    },
+    {
+      "idx": 86,
+      "version": "7",
+      "when": 1778976000000,
+      "tag": "0086_routine_env_runtime_contract",
+      "breakpoints": true
+    },
+    {
+      "idx": 87,
+      "version": "7",
+      "when": 1779360000000,
+      "tag": "0087_backfill_environment_manage_human_defaults",
+      "breakpoints": true
+    },
+    {
+      "idx": 88,
+      "version": "7",
+      "when": 1779446400000,
+      "tag": "0088_backfill_principal_access_compatibility",
+      "breakpoints": true
+    },
+    {
+      "idx": 89,
+      "version": "7",
+      "when": 1779129600000,
+      "tag": "0089_cloud_upstreams",
+      "breakpoints": true
+    },
+    {
+      "idx": 90,
+      "version": "7",
+      "when": 1779573019125,
+      "tag": "0090_resource_memberships",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/agent_memberships.ts

@@ -0,0 +1,25 @@
+import { pgTable, uuid, text, timestamp, uniqueIndex, index } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+
+export const agentMemberships = pgTable(
+  "agent_memberships",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    agentId: uuid("agent_id").notNull().references(() => agents.id, { onDelete: "cascade" }),
+    userId: text("user_id").notNull(),
+    state: text("state").notNull().default("joined"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyUserIdx: index("agent_memberships_company_user_idx").on(table.companyId, table.userId),
+    agentIdx: index("agent_memberships_agent_idx").on(table.agentId),
+    companyUserAgentUq: uniqueIndex("agent_memberships_company_user_agent_uq").on(
+      table.companyId,
+      table.userId,
+      table.agentId,
+    ),
+  }),
+);

packages/db/src/schema/cloud_upstreams.ts

@@ -0,0 +1,75 @@
+import { boolean, index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+
+export const cloudUpstreamConnections = pgTable(
+  "cloud_upstream_connections",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    remoteUrl: text("remote_url").notNull(),
+    sourceInstanceId: text("source_instance_id").notNull(),
+    sourceInstanceFingerprint: text("source_instance_fingerprint").notNull(),
+    sourcePublicKey: text("source_public_key").notNull(),
+    // Stored through the Cloud Upstream service as an encrypted credential envelope.
+    privateKeyPem: text("private_key_pem").notNull(),
+    tokenStatus: text("token_status").notNull(),
+    scopes: text("scopes").array().notNull().default([]),
+    authorizedGlobalUserId: text("authorized_global_user_id"),
+    // Stored through the Cloud Upstream service as an encrypted credential envelope.
+    accessToken: text("access_token"),
+    tokenId: text("token_id"),
+    tokenExpiresAt: timestamp("token_expires_at", { withTimezone: true }),
+
+    targetStackId: text("target_stack_id").notNull(),
+    targetStackSlug: text("target_stack_slug"),
+    targetStackDisplayName: text("target_stack_display_name"),
+    targetCompanyId: text("target_company_id").notNull(),
+    targetOrigin: text("target_origin").notNull(),
+    targetPrimaryHost: text("target_primary_host").notNull(),
+    targetProduct: text("target_product").notNull(),
+    targetSchemaMajor: integer("target_schema_major").notNull(),
+    targetMaxChunkBytes: integer("target_max_chunk_bytes").notNull(),
+
+    pendingState: text("pending_state"),
+    pendingCodeVerifier: text("pending_code_verifier"),
+    pendingRedirectUri: text("pending_redirect_uri"),
+    pendingTokenUrl: text("pending_token_url"),
+
+    lastRunId: uuid("last_run_id"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index("cloud_upstream_connections_company_idx").on(table.companyId),
+  ],
+);
+
+export const cloudUpstreamRuns = pgTable(
+  "cloud_upstream_runs",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    connectionId: uuid("connection_id").notNull().references(() => cloudUpstreamConnections.id, { onDelete: "cascade" }),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    remoteRunId: text("remote_run_id"),
+    status: text("status").notNull(),
+    activeStep: text("active_step").notNull(),
+    progressPercent: integer("progress_percent").notNull().default(0),
+    dryRun: boolean("dry_run").notNull().default(false),
+    retryOfRunId: uuid("retry_of_run_id"),
+    summary: jsonb("summary").$type<import("@paperclipai/shared").CloudUpstreamSummaryCount[]>().notNull().default([]),
+    warnings: jsonb("warnings").$type<import("@paperclipai/shared").CloudUpstreamWarning[]>().notNull().default([]),
+    conflicts: jsonb("conflicts").$type<import("@paperclipai/shared").CloudUpstreamConflict[]>().notNull().default([]),
+    events: jsonb("events").$type<import("@paperclipai/shared").CloudUpstreamRunEvent[]>().notNull().default([]),
+    report: jsonb("report").$type<Record<string, unknown>>().notNull().default({}),
+    idempotencyKey: text("idempotency_key").notNull(),
+    manifestHash: text("manifest_hash").notNull(),
+    targetUrl: text("target_url"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+    completedAt: timestamp("completed_at", { withTimezone: true }),
+  },
+  (table) => [
+    index("cloud_upstream_runs_company_created_idx").on(table.companyId, table.createdAt),
+    index("cloud_upstream_runs_connection_idx").on(table.connectionId),
+  ],
+);

packages/db/src/schema/documents.ts

@@ -16,6 +16,9 @@ export const documents = pgTable(
     createdByUserId: text("created_by_user_id"),
     updatedByAgentId: uuid("updated_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
     updatedByUserId: text("updated_by_user_id"),
+    lockedAt: timestamp("locked_at", { withTimezone: true }),
+    lockedByAgentId: uuid("locked_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
+    lockedByUserId: text("locked_by_user_id"),
     createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
     updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
   },

packages/db/src/schema/index.ts

@@ -2,9 +2,11 @@ export { companies } from "./companies.js";
 export { companyLogos } from "./company_logos.js";
 export { authUsers, authSessions, authAccounts, authVerifications } from "./auth.js";
 export { instanceSettings } from "./instance_settings.js";
+export { cloudUpstreamConnections, cloudUpstreamRuns } from "./cloud_upstreams.js";
 export { instanceUserRoles } from "./instance_user_roles.js";
 export { userSidebarPreferences } from "./user_sidebar_preferences.js";
 export { agents } from "./agents.js";
+export { agentMemberships } from "./agent_memberships.js";
 export { boardApiKeys } from "./board_api_keys.js";
 export { cliAuthChallenges } from "./cli_auth_challenges.js";
 export { companyMemberships } from "./company_memberships.js";
@@ -20,6 +22,7 @@ export { agentRuntimeState } from "./agent_runtime_state.js";
 export { agentTaskSessions } from "./agent_task_sessions.js";
 export { agentWakeupRequests } from "./agent_wakeup_requests.js";
 export { projects } from "./projects.js";
+export { projectMemberships } from "./project_memberships.js";
 export { projectWorkspaces } from "./project_workspaces.js";
 export { executionWorkspaces } from "./execution_workspaces.js";
 export { environments } from "./environments.js";

packages/db/src/schema/project_memberships.ts

@@ -0,0 +1,25 @@
+import { pgTable, uuid, text, timestamp, uniqueIndex, index } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { projects } from "./projects.js";
+
+export const projectMemberships = pgTable(
+  "project_memberships",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    projectId: uuid("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
+    userId: text("user_id").notNull(),
+    state: text("state").notNull().default("joined"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyUserIdx: index("project_memberships_company_user_idx").on(table.companyId, table.userId),
+    projectIdx: index("project_memberships_project_idx").on(table.projectId),
+    companyUserProjectUq: uniqueIndex("project_memberships_company_user_project_uq").on(
+      table.companyId,
+      table.userId,
+      table.projectId,
+    ),
+  }),
+);

packages/db/src/schema/routines.ts

@@ -17,7 +17,7 @@ import { issues } from "./issues.js";
 import { projects } from "./projects.js";
 import { goals } from "./goals.js";
 import { heartbeatRuns } from "./heartbeat_runs.js";
-import type { RoutineRevisionSnapshotV1, RoutineVariable } from "@paperclipai/shared";
+import type { RoutineEnvConfig, RoutineRevisionSnapshotV1, RoutineVariable } from "@paperclipai/shared";
 
 export const routines = pgTable(
   "routines",
@@ -35,6 +35,7 @@ export const routines = pgTable(
     concurrencyPolicy: text("concurrency_policy").notNull().default("coalesce_if_active"),
     catchUpPolicy: text("catch_up_policy").notNull().default("skip_missed"),
     variables: jsonb("variables").$type<RoutineVariable[]>().notNull().default([]),
+    env: jsonb("env").$type<RoutineEnvConfig>(),
     latestRevisionId: uuid("latest_revision_id"),
     latestRevisionNumber: integer("latest_revision_number").notNull().default(1),
     createdByAgentId: uuid("created_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
@@ -131,6 +132,7 @@ export const routineRuns = pgTable(
     source: text("source").notNull(),
     status: text("status").notNull().default("received"),
     triggeredAt: timestamp("triggered_at", { withTimezone: true }).notNull().defaultNow(),
+    routineRevisionId: uuid("routine_revision_id").references(() => routineRevisions.id, { onDelete: "set null" }),
     idempotencyKey: text("idempotency_key"),
     triggerPayload: jsonb("trigger_payload").$type<Record<string, unknown>>(),
     dispatchFingerprint: text("dispatch_fingerprint"),
@@ -143,6 +145,7 @@ export const routineRuns = pgTable(
   },
   (table) => ({
     companyRoutineIdx: index("routine_runs_company_routine_idx").on(table.companyId, table.routineId, table.createdAt),
+    routineRevisionIdx: index("routine_runs_revision_idx").on(table.routineRevisionId),
     triggerIdx: index("routine_runs_trigger_idx").on(table.triggerId, table.createdAt),
     dispatchFingerprintIdx: index("routine_runs_dispatch_fingerprint_idx").on(table.routineId, table.dispatchFingerprint),
     linkedIssueIdx: index("routine_runs_linked_issue_idx").on(table.linkedIssueId),

packages/db/src/test-embedded-postgres.ts

@@ -3,6 +3,7 @@ import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { applyPendingMigrations, ensurePostgresDatabase } from "./client.js";
+import { prepareEmbeddedPostgresNativeRuntime } from "./embedded-postgres-native.js";
 
 type EmbeddedPostgresInstance = {
   initialise(): Promise<void>;
@@ -48,6 +49,7 @@ function getReservedTestPorts(): Set<number> {
 
 async function getEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
   const mod = await import("embedded-postgres");
+  await prepareEmbeddedPostgresNativeRuntime();
   return mod.default as EmbeddedPostgresCtor;
 }
 

packages/plugins/examples/plugin-kitchen-sink-example/src/constants.ts

@@ -7,6 +7,7 @@ export const PAGE_ROUTE = "kitchensink";
 export const SLOT_IDS = {
   page: "kitchen-sink-page",
   settingsPage: "kitchen-sink-settings-page",
+  companySettingsPage: "kitchen-sink-company-settings-page",
   dashboardWidget: "kitchen-sink-dashboard-widget",
   sidebar: "kitchen-sink-sidebar-link",
   sidebarPanel: "kitchen-sink-sidebar-panel",
@@ -23,6 +24,7 @@ export const SLOT_IDS = {
 export const EXPORT_NAMES = {
   page: "KitchenSinkPage",
   settingsPage: "KitchenSinkSettingsPage",
+  companySettingsPage: "KitchenSinkCompanySettingsPage",
   dashboardWidget: "KitchenSinkDashboardWidget",
   sidebar: "KitchenSinkSidebarLink",
   sidebarPanel: "KitchenSinkSidebarPanel",

packages/plugins/examples/plugin-kitchen-sink-example/src/manifest.ts

@@ -194,6 +194,13 @@ const manifest: PaperclipPluginManifestV1 = {
         displayName: "Kitchen Sink Settings",
         exportName: EXPORT_NAMES.settingsPage,
       },
+      {
+        type: "companySettingsPage",
+        id: SLOT_IDS.companySettingsPage,
+        displayName: "Kitchen Sink",
+        exportName: EXPORT_NAMES.companySettingsPage,
+        routePath: "kitchen-sink",
+      },
       {
         type: "dashboardWidget",
         id: SLOT_IDS.dashboardWidget,

packages/plugins/examples/plugin-kitchen-sink-example/src/ui/index.tsx

@@ -10,6 +10,7 @@ import {
   usePluginToast,
   type PluginCommentAnnotationProps,
   type PluginCommentContextMenuItemProps,
+  type PluginCompanySettingsPageProps,
   type PluginDetailTabProps,
   type PluginPageProps,
   type PluginProjectSidebarItemProps,
@@ -2236,6 +2237,33 @@ export function KitchenSinkSettingsPage({ context }: PluginSettingsPageProps) {
   );
 }
 
+export function KitchenSinkCompanySettingsPage({ context }: PluginCompanySettingsPageProps) {
+  const hostNavigation = useHostNavigation();
+  const overview = usePluginOverview(context.companyId);
+  const href = hostNavigation.resolveHref("/company/settings/kitchen-sink");
+
+  return (
+    <div style={layoutStack}>
+      <Section title="Company Settings Slot">
+        <div style={subtleCardStyle}>
+          <div style={{ display: "grid", gap: "8px" }}>
+            <strong>Mounted inside company settings</strong>
+            <div style={mutedTextStyle}>
+              This fixture proves a ready plugin can add a settings sidebar item and render with company context.
+            </div>
+            <JsonBlock value={{
+              companyId: context.companyId,
+              companyPrefix: context.companyPrefix,
+              route: href,
+              pluginId: overview.data?.pluginId ?? PLUGIN_ID,
+            }} />
+          </div>
+        </div>
+      </Section>
+    </div>
+  );
+}
+
 export function KitchenSinkDashboardWidget({ context }: PluginWidgetProps) {
   const hostNavigation = useHostNavigation();
   const overview = usePluginOverview(context.companyId);

packages/plugins/plugin-llm-wiki/migrations/003_spaces.sql

@@ -140,37 +140,14 @@ ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_runs ALTER COLUMN
 ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_source_snapshots ALTER COLUMN space_id SET NOT NULL;
 ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings ALTER COLUMN space_id SET NOT NULL;
 
-DO $$
-DECLARE
-  target record;
-  constraint_name text;
-BEGIN
-  FOR target IN
-    SELECT * FROM (VALUES
-      ('wiki_pages', ARRAY['company_id', 'wiki_id', 'path']::text[]),
-      ('paperclip_distillation_cursors', ARRAY['company_id', 'wiki_id', 'source_scope', 'scope_key', 'source_kind']::text[]),
-      ('paperclip_distillation_work_items', ARRAY['company_id', 'wiki_id', 'idempotency_key']::text[]),
-      ('paperclip_page_bindings', ARRAY['company_id', 'wiki_id', 'page_path']::text[])
-    ) AS targets(table_name, column_names)
-  LOOP
-    FOR constraint_name IN
-      SELECT c.conname
-      FROM pg_constraint c
-      JOIN pg_class t ON t.oid = c.conrelid
-      JOIN pg_namespace n ON n.oid = t.relnamespace
-      WHERE n.nspname = 'plugin_llm_wiki_8f50da974f'
-        AND t.relname = target.table_name
-        AND c.contype = 'u'
-        AND (
-          SELECT array_agg(a.attname ORDER BY constraint_columns.ordinality)::text[]
-          FROM unnest(c.conkey) WITH ORDINALITY AS constraint_columns(attnum, ordinality)
-          JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = constraint_columns.attnum
-        ) = target.column_names
-    LOOP
-      EXECUTE format('ALTER TABLE %I.%I DROP CONSTRAINT %I', 'plugin_llm_wiki_8f50da974f', target.table_name, constraint_name);
-    END LOOP;
-  END LOOP;
-END $$;
+ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
+  DROP CONSTRAINT IF EXISTS wiki_pages_company_id_wiki_id_path_key;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_cursors
+  DROP CONSTRAINT IF EXISTS paperclip_distillation_cursor_company_id_wiki_id_source_sco_key;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_distillation_work_items
+  DROP CONSTRAINT IF EXISTS paperclip_distillation_work_i_company_id_wiki_id_idempotenc_key;
+ALTER TABLE plugin_llm_wiki_8f50da974f.paperclip_page_bindings
+  DROP CONSTRAINT IF EXISTS paperclip_page_bindings_company_id_wiki_id_page_path_key;
 
 ALTER TABLE plugin_llm_wiki_8f50da974f.wiki_pages
   DROP CONSTRAINT IF EXISTS wiki_pages_company_wiki_space_path_key;

packages/plugins/plugin-llm-wiki/package.json

@@ -4,6 +4,14 @@
   "type": "module",
   "private": true,
   "description": "Local-file LLM Wiki plugin for source ingestion, wiki browsing, query, lint, and maintenance workflows.",
+  "files": [
+    "agents",
+    "dist",
+    "migrations",
+    "skills",
+    "templates",
+    "README.md"
+  ],
   "scripts": {
     "prebuild": "pnpm --filter @paperclipai/plugin-sdk ensure-build-deps",
     "build": "node ./esbuild.config.mjs",

packages/plugins/plugin-llm-wiki/src/templates.ts

@@ -46,7 +46,7 @@ export const DEFAULT_AGENT_INSTRUCTIONS = DEFAULT_AGENT_INSTRUCTION_FILES["AGENT
 export const DEFAULT_IDEA = templateFile("IDEA.md");
 export const DEFAULT_INDEX = templateFile("wiki/index.md");
 export const DEFAULT_LOG = templateFile("wiki/log.md");
-export const DEFAULT_GITIGNORE = templateFile(".gitignore");
+export const DEFAULT_GITIGNORE = templateFile("gitignore.template");
 
 export const QUERY_PROMPT = `Answer from the LLM Wiki using the installed wiki-query skill.
 

packages/plugins/plugin-llm-wiki/src/ui/app.tsx

@@ -155,6 +155,11 @@ type ManagedRoutine = {
   } | null;
 };
 
+type ManagedRoutineDefaultDrift = NonNullable<ManagedRoutine["defaultDrift"]>;
+type ManagedRoutinesListItemWithDrift = ManagedRoutinesListItem & {
+  defaultDrift?: ManagedRoutineDefaultDrift | null;
+};
+
 type ManagedSkill = {
   status: string;
   skillId?: string | null;
@@ -5905,7 +5910,7 @@ function SettingsBody({ context, initialSection = "root" }: { context: { company
   const effectiveSelectedProjectId = selectedProjectId || data.managedProject.projectId || "";
   const currentProjectOption = projectOptions.find((project) => project.id === effectiveSelectedProjectId) ?? projectFallbackOption;
   const currentEventPolicy = eventPolicy ?? data.eventIngestion;
-  const managedRoutineItems: ManagedRoutinesListItem[] = managedRoutines.map((routine) => {
+  const managedRoutineItems: ManagedRoutinesListItemWithDrift[] = managedRoutines.map((routine) => {
     const fallback = routineFallbackFor(routine);
     const key = routine.resourceKey ?? routine.routineId ?? fallback.title;
     const status = managedRoutineStatus(routine);
@@ -6132,7 +6137,7 @@ function SettingsBody({ context, initialSection = "root" }: { context: { company
 
   async function resetManagedRoutineToDefaults(routine: ManagedRoutinesListItem) {
     if (!context.companyId || !routine.resourceKey) return;
-    const changedFields = routine.defaultDrift?.changedFields ?? [];
+    const changedFields = (routine as ManagedRoutinesListItemWithDrift).defaultDrift?.changedFields ?? [];
     const fieldList = changedFields.length > 0 ? changedFields.join(", ") : "managed defaults";
     const confirmed = typeof window === "undefined" || window.confirm(
       `Update "${routine.title}" to the current LLM Wiki plugin defaults? This replaces ${fieldList}. Cancel to keep the current custom routine text.`,

packages/plugins/plugin-llm-wiki/src/wiki/core.ts

@@ -1102,10 +1102,10 @@ export async function listPaperclipIngestionCandidates(ctx: PluginContext, input
   return { projects, rootIssues: issues };
 }
 
-export async function updateEventIngestionSettings(
-  ctx: PluginContext,
+  export async function updateEventIngestionSettings(
+    ctx: PluginContext,
   input: { companyId: string; settings: WikiEventIngestionSettingsUpdate },
-): Promise<WikiEventIngestionSettings> {
+  ): Promise<WikiEventIngestionSettings> {
   await requirePaperclipIngestionPolicy(ctx, {
     companyId: input.companyId,
     wikiId: normalizeWikiId(input.settings.wikiId),