more docs on workspace strategy'

.agents/skills/pr-report/SKILL.md

@@ -1,202 +0,0 @@
----
-name: pr-report
-description: >
-  Review a pull request or contribution deeply, explain it tutorial-style for a
-  maintainer, and produce a polished report artifact such as HTML or Markdown.
-  Use when asked to analyze a PR, explain a contributor's design decisions,
-  compare it with similar systems, or prepare a merge recommendation.
----
-
-# PR Report Skill
-
-Produce a maintainer-grade review of a PR, branch, or large contribution.
-
-Default posture:
-
-- understand the change before judging it
-- explain the system as built, not just the diff
-- separate architectural problems from product-scope objections
-- make a concrete recommendation, not a vague impression
-
-## When to Use
-
-Use this skill when the user asks for things like:
-
-- "review this PR deeply"
-- "explain this contribution to me"
-- "make me a report or webpage for this PR"
-- "compare this design to similar systems"
-- "should I merge this?"
-
-## Outputs
-
-Common outputs:
-
-- standalone HTML report in `tmp/reports/...`
-- Markdown report in `report/` or another requested folder
-- short maintainer summary in chat
-
-If the user asks for a webpage, build a polished standalone HTML artifact with
-clear sections and readable visual hierarchy.
-
-Resources bundled with this skill:
-
-- `references/style-guide.md` for visual direction and report presentation rules
-- `assets/html-report-starter.html` for a reusable standalone HTML/CSS starter
-
-## Workflow
-
-### 1. Acquire and frame the target
-
-Work from local code when possible, not just the GitHub PR page.
-
-Gather:
-
-- target branch or worktree
-- diff size and changed subsystems
-- relevant repo docs, specs, and invariants
-- contributor intent if it is documented in PR text or design docs
-
-Start by answering: what is this change *trying* to become?
-
-### 2. Build a mental model of the system
-
-Do not stop at file-by-file notes. Reconstruct the design:
-
-- what new runtime or contract exists
-- which layers changed: db, shared types, server, UI, CLI, docs
-- lifecycle: install, startup, execution, UI, failure, disablement
-- trust boundary: what code runs where, under what authority
-
-For large contributions, include a tutorial-style section that teaches the
-system from first principles.
-
-### 3. Review like a maintainer
-
-Findings come first. Order by severity.
-
-Prioritize:
-
-- behavioral regressions
-- trust or security gaps
-- misleading abstractions
-- lifecycle and operational risks
-- coupling that will be hard to unwind
-- missing tests or unverifiable claims
-
-Always cite concrete file references when possible.
-
-### 4. Distinguish the objection type
-
-Be explicit about whether a concern is:
-
-- product direction
-- architecture
-- implementation quality
-- rollout strategy
-- documentation honesty
-
-Do not hide an architectural objection inside a scope objection.
-
-### 5. Compare to external precedents when needed
-
-If the contribution introduces a framework or platform concept, compare it to
-similar open-source systems.
-
-When comparing:
-
-- prefer official docs or source
-- focus on extension boundaries, context passing, trust model, and UI ownership
-- extract lessons, not just similarities
-
-Good comparison questions:
-
-- Who owns lifecycle?
-- Who owns UI composition?
-- Is context explicit or ambient?
-- Are plugins trusted code or sandboxed code?
-- Are extension points named and typed?
-
-### 6. Make the recommendation actionable
-
-Do not stop at "merge" or "do not merge."
-
-Choose one:
-
-- merge as-is
-- merge after specific redesign
-- salvage specific pieces
-- keep as design research
-
-If rejecting or narrowing, say what should be kept.
-
-Useful recommendation buckets:
-
-- keep the protocol/type model
-- redesign the UI boundary
-- narrow the initial surface area
-- defer third-party execution
-- ship a host-owned extension-point model first
-
-### 7. Build the artifact
-
-Suggested report structure:
-
-1. Executive summary
-2. What the PR actually adds
-3. Tutorial: how the system works
-4. Strengths
-5. Main findings
-6. Comparisons
-7. Recommendation
-
-For HTML reports:
-
-- use intentional typography and color
-- make navigation easy for long reports
-- favor strong section headings and small reference labels
-- avoid generic dashboard styling
-
-Before building from scratch, read `references/style-guide.md`.
-If a fast polished starter is helpful, begin from `assets/html-report-starter.html`
-and replace the placeholder content with the actual report.
-
-### 8. Verify before handoff
-
-Check:
-
-- artifact path exists
-- findings still match the actual code
-- any requested forbidden strings are absent from generated output
-- if tests were not run, say so explicitly
-
-## Review Heuristics
-
-### Plugin and platform work
-
-Watch closely for:
-
-- docs claiming sandboxing while runtime executes trusted host processes
-- module-global state used to smuggle React context
-- hidden dependence on render order
-- plugins reaching into host internals instead of using explicit APIs
-- "capabilities" that are really policy labels on top of fully trusted code
-
-### Good signs
-
-- typed contracts shared across layers
-- explicit extension points
-- host-owned lifecycle
-- honest trust model
-- narrow first rollout with room to grow
-
-## Final Response
-
-In chat, summarize:
-
-- where the report is
-- your overall call
-- the top one or two reasons
-- whether verification or tests were skipped
-
-Keep the chat summary shorter than the report itself.

.agents/skills/pr-report/assets/html-report-starter.html

@@ -1,426 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>PR Report Starter</title>
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link
-      href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600;700&family=Newsreader:opsz,wght@6..72,500;6..72,700&display=swap"
-      rel="stylesheet"
-    />
-    <style>
-      :root {
-        --bg: #f4efe5;
-        --paper: rgba(255, 251, 244, 0.88);
-        --paper-strong: #fffaf1;
-        --ink: #1f1b17;
-        --muted: #6a6257;
-        --line: rgba(31, 27, 23, 0.12);
-        --accent: #9c4729;
-        --accent-soft: rgba(156, 71, 41, 0.1);
-        --good: #2f6a42;
-        --warn: #946200;
-        --bad: #8c2f25;
-        --shadow: 0 22px 60px rgba(52, 37, 19, 0.1);
-        --radius: 20px;
-      }
-
-      * {
-        box-sizing: border-box;
-      }
-
-      html {
-        scroll-behavior: smooth;
-      }
-
-      body {
-        margin: 0;
-        color: var(--ink);
-        font-family: "IBM Plex Sans", sans-serif;
-        background:
-          radial-gradient(circle at top left, rgba(156, 71, 41, 0.12), transparent 34rem),
-          radial-gradient(circle at top right, rgba(47, 106, 66, 0.08), transparent 28rem),
-          linear-gradient(180deg, #efe6d6 0%, var(--bg) 48%, #ece5d8 100%);
-      }
-
-      .shell {
-        width: min(1360px, calc(100vw - 32px));
-        margin: 24px auto;
-        display: grid;
-        grid-template-columns: 280px minmax(0, 1fr);
-        gap: 24px;
-      }
-
-      .panel {
-        background: var(--paper);
-        backdrop-filter: blur(12px);
-        border: 1px solid var(--line);
-        border-radius: var(--radius);
-        box-shadow: var(--shadow);
-      }
-
-      .nav {
-        position: sticky;
-        top: 20px;
-        align-self: start;
-        padding: 22px;
-      }
-
-      .eyebrow {
-        letter-spacing: 0.12em;
-        text-transform: uppercase;
-        font-size: 11px;
-        font-weight: 700;
-        color: var(--accent);
-      }
-
-      .nav h1,
-      .hero h1,
-      h2,
-      h3 {
-        font-family: "Newsreader", serif;
-        line-height: 0.96;
-        margin: 0;
-      }
-
-      .nav h1 {
-        font-size: 2rem;
-        margin-top: 10px;
-      }
-
-      .nav p {
-        color: var(--muted);
-        font-size: 0.95rem;
-        line-height: 1.5;
-      }
-
-      .nav ul {
-        list-style: none;
-        padding: 0;
-        margin: 18px 0 0;
-        display: grid;
-        gap: 10px;
-      }
-
-      .nav a {
-        display: block;
-        color: var(--ink);
-        text-decoration: none;
-        padding: 10px 12px;
-        border-radius: 12px;
-        border: 1px solid transparent;
-        background: rgba(255, 255, 255, 0.35);
-      }
-
-      .nav a:hover {
-        border-color: var(--line);
-        background: rgba(255, 255, 255, 0.75);
-      }
-
-      .meta-block {
-        margin-top: 20px;
-        padding-top: 18px;
-        border-top: 1px solid var(--line);
-        color: var(--muted);
-        font-size: 0.86rem;
-        line-height: 1.5;
-      }
-
-      main {
-        display: grid;
-        gap: 24px;
-      }
-
-      section {
-        padding: 26px 28px 28px;
-      }
-
-      .hero {
-        padding: 28px;
-        overflow: hidden;
-        position: relative;
-      }
-
-      .hero::after {
-        content: "";
-        position: absolute;
-        inset: auto -3rem -6rem auto;
-        width: 18rem;
-        height: 18rem;
-        border-radius: 50%;
-        background: radial-gradient(circle, rgba(156, 71, 41, 0.14), transparent 68%);
-        pointer-events: none;
-      }
-
-      .hero h1 {
-        font-size: clamp(2.6rem, 5vw, 4.6rem);
-        max-width: 12ch;
-        margin-top: 12px;
-      }
-
-      .lede {
-        margin-top: 16px;
-        max-width: 70ch;
-        font-size: 1.05rem;
-        line-height: 1.65;
-        color: #2b2723;
-      }
-
-      .hero-grid,
-      .card-grid,
-      .two-col {
-        display: grid;
-        gap: 14px;
-      }
-
-      .hero-grid {
-        margin-top: 24px;
-        grid-template-columns: repeat(4, minmax(0, 1fr));
-      }
-
-      .card-grid {
-        grid-template-columns: repeat(2, minmax(0, 1fr));
-      }
-
-      .two-col {
-        grid-template-columns: repeat(2, minmax(0, 1fr));
-      }
-
-      .metric,
-      .card,
-      .finding {
-        padding: 18px;
-        background: rgba(255, 255, 255, 0.68);
-        border: 1px solid var(--line);
-        border-radius: 18px;
-      }
-
-      .metric .label {
-        color: var(--muted);
-        font-size: 0.82rem;
-        text-transform: uppercase;
-        letter-spacing: 0.08em;
-      }
-
-      .metric .value {
-        margin-top: 8px;
-        font-size: 1.45rem;
-        font-weight: 700;
-      }
-
-      h2 {
-        font-size: 2rem;
-        margin-bottom: 16px;
-      }
-
-      h3 {
-        font-size: 1.3rem;
-        margin-bottom: 10px;
-      }
-
-      p {
-        margin: 0 0 14px;
-        line-height: 1.65;
-      }
-
-      ul,
-      ol {
-        margin: 0;
-        padding-left: 20px;
-        line-height: 1.65;
-      }
-
-      li + li {
-        margin-top: 8px;
-      }
-
-      .badge-row {
-        display: flex;
-        flex-wrap: wrap;
-        gap: 8px;
-        margin: 18px 0 8px;
-      }
-
-      .badge {
-        display: inline-flex;
-        align-items: center;
-        gap: 8px;
-        padding: 8px 10px;
-        border-radius: 999px;
-        font-size: 0.82rem;
-        font-weight: 700;
-        border: 1px solid var(--line);
-        background: rgba(255, 255, 255, 0.68);
-      }
-
-      .badge.good {
-        color: var(--good);
-      }
-
-      .badge.warn {
-        color: var(--warn);
-      }
-
-      .badge.bad {
-        color: var(--bad);
-      }
-
-      .quote {
-        margin-top: 18px;
-        padding: 18px;
-        border-left: 4px solid var(--accent);
-        border-radius: 14px;
-        background: var(--accent-soft);
-      }
-
-      .severity {
-        display: inline-flex;
-        margin-bottom: 12px;
-        padding: 6px 10px;
-        border-radius: 999px;
-        font-size: 0.78rem;
-        font-weight: 700;
-        text-transform: uppercase;
-        letter-spacing: 0.08em;
-      }
-
-      .severity.high {
-        background: rgba(140, 47, 37, 0.12);
-        color: var(--bad);
-      }
-
-      .severity.medium {
-        background: rgba(148, 98, 0, 0.12);
-        color: var(--warn);
-      }
-
-      .severity.low {
-        background: rgba(47, 106, 66, 0.12);
-        color: var(--good);
-      }
-
-      .ref {
-        color: var(--muted);
-        font-size: 0.82rem;
-        line-height: 1.5;
-      }
-
-      @media (max-width: 980px) {
-        .shell {
-          grid-template-columns: 1fr;
-        }
-
-        .nav {
-          position: static;
-        }
-
-        .hero-grid,
-        .card-grid,
-        .two-col {
-          grid-template-columns: 1fr;
-        }
-
-        .hero h1 {
-          max-width: 100%;
-        }
-      }
-    </style>
-  </head>
-  <body>
-    <div class="shell">
-      <aside class="panel nav">
-        <div class="eyebrow">Maintainer Report</div>
-        <h1>Report Title</h1>
-        <p>Replace this with a concise description of what the report covers.</p>
-        <ul>
-          <li><a href="#summary">Summary</a></li>
-          <li><a href="#tutorial">Tutorial</a></li>
-          <li><a href="#findings">Findings</a></li>
-          <li><a href="#recommendation">Recommendation</a></li>
-        </ul>
-        <div class="meta-block">
-          Replace with project metadata, review date, or scope notes.
-        </div>
-      </aside>
-
-      <main>
-        <section class="panel hero" id="summary">
-          <div class="eyebrow">Executive Summary</div>
-          <h1>Use the hero for the clearest one-line judgment.</h1>
-          <p class="lede">
-            Replace this with the short explanation of what the contribution does, why it matters,
-            and what the core maintainer question is.
-          </p>
-          <div class="badge-row">
-            <span class="badge good">Strength</span>
-            <span class="badge warn">Tradeoff</span>
-            <span class="badge bad">Risk</span>
-          </div>
-          <div class="hero-grid">
-            <div class="metric">
-              <div class="label">Overall Call</div>
-              <div class="value">Placeholder</div>
-            </div>
-            <div class="metric">
-              <div class="label">Main Concern</div>
-              <div class="value">Placeholder</div>
-            </div>
-            <div class="metric">
-              <div class="label">Best Part</div>
-              <div class="value">Placeholder</div>
-            </div>
-            <div class="metric">
-              <div class="label">Weakest Part</div>
-              <div class="value">Placeholder</div>
-            </div>
-          </div>
-          <div class="quote">
-            Use this block for the thesis, a sharp takeaway, or a key cited point.
-          </div>
-        </section>
-
-        <section class="panel" id="tutorial">
-          <h2>Tutorial Section</h2>
-          <div class="two-col">
-            <div class="card">
-              <h3>Concept Card</h3>
-              <p>Use cards for mental models, subsystems, or comparison slices.</p>
-              <div class="ref">path/to/file.ts:10</div>
-            </div>
-            <div class="card">
-              <h3>Second Card</h3>
-              <p>Keep cards fairly dense. This template is about style, not fixed structure.</p>
-              <div class="ref">path/to/file.ts:20</div>
-            </div>
-          </div>
-        </section>
-
-        <section class="panel" id="findings">
-          <h2>Findings</h2>
-          <article class="finding">
-            <div class="severity high">High</div>
-            <h3>Finding Title</h3>
-            <p>Use findings for the sharpest judgment calls and risks.</p>
-            <div class="ref">path/to/file.ts:30</div>
-          </article>
-        </section>
-
-        <section class="panel" id="recommendation">
-          <h2>Recommendation</h2>
-          <div class="card-grid">
-            <div class="card">
-              <h3>Path Forward</h3>
-              <p>Use this area for merge guidance, salvage plan, or rollout advice.</p>
-            </div>
-            <div class="card">
-              <h3>What To Keep</h3>
-              <p>Call out the parts worth preserving even if the whole proposal should not land.</p>
-            </div>
-          </div>
-        </section>
-      </main>
-    </div>
-  </body>
-</html>

.agents/skills/pr-report/references/style-guide.md

@@ -1,149 +0,0 @@
-# PR Report Style Guide
-
-Use this guide when the user wants a report artifact, especially a webpage.
-
-## Goal
-
-Make the report feel like an editorial review, not an internal admin dashboard.
-The page should make a long technical argument easy to scan without looking
-generic or overdesigned.
-
-## Visual Direction
-
-Preferred tone:
-
-- editorial
-- warm
-- serious
-- high-contrast
-- handcrafted, not corporate SaaS
-
-Avoid:
-
-- default app-shell layouts
-- purple gradients on white
-- generic card dashboards
-- cramped pages with weak hierarchy
-- novelty fonts that hurt readability
-
-## Typography
-
-Recommended pattern:
-
-- one expressive serif or display face for major headings
-- one sturdy sans-serif for body copy and UI labels
-
-Good combinations:
-
-- Newsreader + IBM Plex Sans
-- Source Serif 4 + Instrument Sans
-- Fraunces + Public Sans
-- Libre Baskerville + Work Sans
-
-Rules:
-
-- headings should feel deliberate and large
-- body copy should stay comfortable for long reading
-- reference labels and badges should use smaller dense sans text
-
-## Layout
-
-Recommended structure:
-
-- a sticky side or top navigation for long reports
-- one strong hero summary at the top
-- panel or paper-like sections for each major topic
-- multi-column card grids for comparisons and strengths
-- single-column body text for findings and recommendations
-
-Use generous spacing. Long-form technical reports need breathing room.
-
-## Color
-
-Prefer muted paper-like backgrounds with one warm accent and one cool counterweight.
-
-Suggested token categories:
-
-- `--bg`
-- `--paper`
-- `--ink`
-- `--muted`
-- `--line`
-- `--accent`
-- `--good`
-- `--warn`
-- `--bad`
-
-The accent should highlight navigation, badges, and important labels. Do not
-let accent colors dominate body text.
-
-## Useful UI Elements
-
-Include small reusable styles for:
-
-- summary metrics
-- badges
-- quotes or callouts
-- finding cards
-- severity labels
-- reference labels
-- comparison cards
-- responsive two-column sections
-
-## Motion
-
-Keep motion restrained.
-
-Good:
-
-- soft fade/slide-in on first load
-- hover response on nav items or cards
-
-Bad:
-
-- constant animation
-- floating blobs
-- decorative motion with no reading benefit
-
-## Content Presentation
-
-Even when the user wants design polish, clarity stays primary.
-
-Good structure for long reports:
-
-1. executive summary
-2. what changed
-3. tutorial explanation
-4. strengths
-5. findings
-6. comparisons
-7. recommendation
-
-The exact headings can change. The important thing is to separate explanation
-from judgment.
-
-## References
-
-Reference labels should be visually quiet but easy to spot.
-
-Good pattern:
-
-- small muted text
-- monospace or compact sans
-- keep them close to the paragraph they support
-
-## Starter Usage
-
-If you need a fast polished base, start from:
-
-- `assets/html-report-starter.html`
-
-Customize:
-
-- fonts
-- color tokens
-- hero copy
-- section ordering
-- card density
-
-Do not preserve the placeholder sections if they do not fit the actual report.

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

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

.github/workflows/pr-policy.yml

@@ -13,8 +13,6 @@ jobs:
   policy:
     runs-on: ubuntu-latest
     timeout-minutes: 10
-    permissions:
-      pull-requests: read
 
     steps:
       - name: Checkout repository
@@ -33,38 +31,19 @@ jobs:
         with:
           node-version: 20
 
-      - name: Enforce lockfile policy when manifests change
-        env:
-          GH_TOKEN: ${{ github.token }}
+      - name: Block manual lockfile edits
+        if: github.head_ref != 'chore/refresh-lockfile'
         run: |
-          changed="$(gh api "repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files" --paginate --jq '.[].filename')"
-          manifest_pattern='(^|/)package\.json$|^pnpm-workspace\.yaml$|^\.npmrc$|^pnpmfile\.(cjs|js|mjs)$'
-
-          manifest_changed=false
-          lockfile_changed=false
-
-          if printf '%s\n' "$changed" | grep -Eq "$manifest_pattern"; then
-            manifest_changed=true
-          fi
-
+          changed="$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}")"
           if printf '%s\n' "$changed" | grep -qx 'pnpm-lock.yaml'; then
-            lockfile_changed=true
-          fi
-
-          if [ "$lockfile_changed" = true ] && [ "$manifest_changed" != true ]; then
-            echo "pnpm-lock.yaml changed without a dependency manifest change." >&2
+            echo "Do not commit pnpm-lock.yaml in pull requests. CI owns lockfile updates."
             exit 1
           fi
 
-          if [ "$manifest_changed" = true ]; then
+      - name: Validate dependency resolution when manifests change
+        run: |
+          changed="$(git diff --name-only "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}")"
+          manifest_pattern='(^|/)package\.json$|^pnpm-workspace\.yaml$|^\.npmrc$|^pnpmfile\.(cjs|js|mjs)$'
+          if printf '%s\n' "$changed" | grep -Eq "$manifest_pattern"; then
             pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
-
-            if ! git diff --quiet -- pnpm-lock.yaml; then
-              if [ "${{ github.event.pull_request.head.repo.full_name }}" = "${{ github.repository }}" ]; then
-                echo "pnpm-lock.yaml is stale for this PR. Wait for the Refresh Lockfile workflow to push the bot commit, then rerun checks." >&2
-              else
-                echo "pnpm-lock.yaml is stale for this fork PR. Run pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile and commit pnpm-lock.yaml." >&2
-              fi
-              exit 1
-            fi
           fi

.github/workflows/pr-verify.yml

@@ -30,7 +30,7 @@ jobs:
           cache: pnpm
 
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install --no-frozen-lockfile
 
       - name: Typecheck
         run: pnpm -r typecheck

.github/workflows/refresh-lockfile-pr.yml

@@ -1,111 +0,0 @@
-name: Refresh Lockfile
-
-on:
-  pull_request:
-    branches:
-      - master
-    types:
-      - opened
-      - synchronize
-      - reopened
-      - ready_for_review
-
-concurrency:
-  group: refresh-lockfile-pr-${{ github.event.pull_request.number }}
-  cancel-in-progress: true
-
-jobs:
-  refresh:
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    permissions:
-      contents: write
-      pull-requests: read
-
-    steps:
-      - name: Detect dependency manifest changes
-        id: changes
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: |
-          changed="$(gh api "repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files" --paginate --jq '.[].filename')"
-          manifest_pattern='(^|/)package\.json$|^pnpm-workspace\.yaml$|^\.npmrc$|^pnpmfile\.(cjs|js|mjs)$'
-
-          if printf '%s\n' "$changed" | grep -Eq "$manifest_pattern"; then
-            echo "manifest_changed=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "manifest_changed=false" >> "$GITHUB_OUTPUT"
-          fi
-
-          if [ "${{ github.event.pull_request.head.repo.full_name }}" = "${{ github.repository }}" ]; then
-            echo "same_repo=true" >> "$GITHUB_OUTPUT"
-          else
-            echo "same_repo=false" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Checkout pull request head
-        if: steps.changes.outputs.manifest_changed == 'true'
-        uses: actions/checkout@v4
-        with:
-          repository: ${{ github.event.pull_request.head.repo.full_name }}
-          ref: ${{ github.event.pull_request.head.ref }}
-          fetch-depth: 0
-
-      - name: Setup pnpm
-        if: steps.changes.outputs.manifest_changed == 'true'
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9.15.4
-          run_install: false
-
-      - name: Setup Node.js
-        if: steps.changes.outputs.manifest_changed == 'true'
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: pnpm
-
-      - name: Refresh pnpm lockfile
-        if: steps.changes.outputs.manifest_changed == 'true'
-        run: pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
-
-      - name: Fail on unexpected file changes
-        if: steps.changes.outputs.manifest_changed == 'true'
-        run: |
-          changed="$(git status --porcelain)"
-          if [ -z "$changed" ]; then
-            echo "Lockfile is already up to date."
-            exit 0
-          fi
-          if printf '%s\n' "$changed" | grep -Fvq ' pnpm-lock.yaml'; then
-            echo "Unexpected files changed during lockfile refresh:"
-            echo "$changed"
-            exit 1
-          fi
-
-      - name: Commit refreshed lockfile to same-repo PR branch
-        if: steps.changes.outputs.manifest_changed == 'true' && steps.changes.outputs.same_repo == 'true'
-        run: |
-          if git diff --quiet -- pnpm-lock.yaml; then
-            echo "Lockfile unchanged, nothing to do."
-            exit 0
-          fi
-
-          git config user.name "lockfile-bot"
-          git config user.email "lockfile-bot@users.noreply.github.com"
-          git add pnpm-lock.yaml
-          git commit -m "chore(lockfile): refresh pnpm-lock.yaml"
-          git push origin "HEAD:${{ github.event.pull_request.head.ref }}"
-
-      - name: Fail fork PRs that need a lockfile refresh
-        if: steps.changes.outputs.manifest_changed == 'true' && steps.changes.outputs.same_repo != 'true'
-        run: |
-          if git diff --quiet -- pnpm-lock.yaml; then
-            echo "Lockfile unchanged, nothing to do."
-            exit 0
-          fi
-
-          echo "This fork PR changes dependency manifests and requires a refreshed pnpm-lock.yaml." >&2
-          echo "Run: pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile" >&2
-          echo "Then commit pnpm-lock.yaml to the PR branch." >&2
-          exit 1

.github/workflows/refresh-lockfile.yml

@@ -0,0 +1,81 @@
+name: Refresh Lockfile
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+concurrency:
+  group: refresh-lockfile-master
+  cancel-in-progress: false
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9.15.4
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Refresh pnpm lockfile
+        run: pnpm install --lockfile-only --ignore-scripts --no-frozen-lockfile
+
+      - name: Fail on unexpected file changes
+        run: |
+          changed="$(git status --porcelain)"
+          if [ -z "$changed" ]; then
+            echo "Lockfile is already up to date."
+            exit 0
+          fi
+          if printf '%s\n' "$changed" | grep -Fvq ' pnpm-lock.yaml'; then
+            echo "Unexpected files changed during lockfile refresh:"
+            echo "$changed"
+            exit 1
+          fi
+
+      - name: Create or update pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if git diff --quiet -- pnpm-lock.yaml; then
+            echo "Lockfile unchanged, nothing to do."
+            exit 0
+          fi
+
+          BRANCH="chore/refresh-lockfile"
+          git config user.name "lockfile-bot"
+          git config user.email "lockfile-bot@users.noreply.github.com"
+
+          git checkout -B "$BRANCH"
+          git add pnpm-lock.yaml
+          git commit -m "chore(lockfile): refresh pnpm-lock.yaml"
+          git push --force origin "$BRANCH"
+
+          # Create PR if one doesn't already exist
+          existing=$(gh pr list --head "$BRANCH" --json number --jq '.[0].number')
+          if [ -z "$existing" ]; then
+            gh pr create \
+              --head "$BRANCH" \
+              --title "chore(lockfile): refresh pnpm-lock.yaml" \
+              --body "Auto-generated lockfile refresh after dependencies changed on master. This PR only updates pnpm-lock.yaml."
+            echo "Created new PR."
+          else
+            echo "PR #$existing already exists, branch updated via force push."
+          fi

.github/workflows/release.yml

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

Dockerfile

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

README.md

@@ -248,6 +248,8 @@ See [doc/DEVELOPING.md](doc/DEVELOPING.md) for the full development guide.
 
 We welcome contributions. See the [contributing guide](CONTRIBUTING.md) for details.
 
+<!-- TODO: add CONTRIBUTING.md -->
+
 <br/>
 
 ## Community

cli/CHANGELOG.md

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

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclipai",
-  "version": "0.3.0",
+  "version": "0.2.7",
   "description": "Paperclip CLI — orchestrate AI agent teams to run a business",
   "type": "module",
   "bin": {
@@ -37,7 +37,6 @@
     "@paperclipai/adapter-claude-local": "workspace:*",
     "@paperclipai/adapter-codex-local": "workspace:*",
     "@paperclipai/adapter-cursor-local": "workspace:*",
-    "@paperclipai/adapter-gemini-local": "workspace:*",
     "@paperclipai/adapter-opencode-local": "workspace:*",
     "@paperclipai/adapter-pi-local": "workspace:*",
     "@paperclipai/adapter-openclaw-gateway": "workspace:*",

cli/src/__tests__/worktree.test.ts

@@ -1,17 +1,5 @@
-import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import {
-  copyGitHooksToWorktreeGitDir,
-  copySeededSecretsKey,
-  rebindWorkspaceCwd,
-  resolveGitWorktreeAddArgs,
-  resolveWorktreeMakeTargetPath,
-  worktreeInitCommand,
-  worktreeMakeCommand,
-} from "../commands/worktree.js";
+import { describe, expect, it } from "vitest";
 import {
   buildWorktreeConfig,
   buildWorktreeEnvEntries,
@@ -23,20 +11,6 @@ import {
 } from "../commands/worktree-lib.js";
 import type { PaperclipConfig } from "../config/schema.js";
 
-const ORIGINAL_CWD = process.cwd();
-const ORIGINAL_ENV = { ...process.env };
-
-afterEach(() => {
-  process.chdir(ORIGINAL_CWD);
-  for (const key of Object.keys(process.env)) {
-    if (!(key in ORIGINAL_ENV)) delete process.env[key];
-  }
-  for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
-    if (value === undefined) delete process.env[key];
-    else process.env[key] = value;
-  }
-});
-
 function buildSourceConfig(): PaperclipConfig {
   return {
     $meta: {
@@ -100,58 +74,6 @@ describe("worktree helpers", () => {
     expect(sanitizeWorktreeInstanceId("  ")).toBe("worktree");
   });
 
-  it("resolves worktree:make target paths under the user home directory", () => {
-    expect(resolveWorktreeMakeTargetPath("paperclip-pr-432")).toBe(
-      path.resolve(os.homedir(), "paperclip-pr-432"),
-    );
-  });
-
-  it("rejects worktree:make names that are not safe directory/branch names", () => {
-    expect(() => resolveWorktreeMakeTargetPath("paperclip/pr-432")).toThrow(
-      "Worktree name must contain only letters, numbers, dots, underscores, or dashes.",
-    );
-  });
-
-  it("builds git worktree add args for new and existing branches", () => {
-    expect(
-      resolveGitWorktreeAddArgs({
-        branchName: "feature-branch",
-        targetPath: "/tmp/feature-branch",
-        branchExists: false,
-      }),
-    ).toEqual(["worktree", "add", "-b", "feature-branch", "/tmp/feature-branch", "HEAD"]);
-
-    expect(
-      resolveGitWorktreeAddArgs({
-        branchName: "feature-branch",
-        targetPath: "/tmp/feature-branch",
-        branchExists: true,
-      }),
-    ).toEqual(["worktree", "add", "/tmp/feature-branch", "feature-branch"]);
-  });
-
-  it("builds git worktree add args with a start point", () => {
-    expect(
-      resolveGitWorktreeAddArgs({
-        branchName: "my-worktree",
-        targetPath: "/tmp/my-worktree",
-        branchExists: false,
-        startPoint: "public-gh/master",
-      }),
-    ).toEqual(["worktree", "add", "-b", "my-worktree", "/tmp/my-worktree", "public-gh/master"]);
-  });
-
-  it("uses start point even when a local branch with the same name exists", () => {
-    expect(
-      resolveGitWorktreeAddArgs({
-        branchName: "my-worktree",
-        targetPath: "/tmp/my-worktree",
-        branchExists: true,
-        startPoint: "origin/main",
-      }),
-    ).toEqual(["worktree", "add", "-b", "my-worktree", "/tmp/my-worktree", "origin/main"]);
-  });
-
   it("rewrites loopback auth URLs to the new port only", () => {
     expect(rewriteLocalUrlPort("http://127.0.0.1:3100", 3110)).toBe("http://127.0.0.1:3110/");
     expect(rewriteLocalUrlPort("https://paperclip.example", 3110)).toBe("https://paperclip.example");
@@ -184,7 +106,6 @@ describe("worktree helpers", () => {
     const env = buildWorktreeEnvEntries(paths);
     expect(env.PAPERCLIP_HOME).toBe(path.resolve("/tmp/paperclip-worktrees"));
     expect(env.PAPERCLIP_INSTANCE_ID).toBe("feature-worktree-support");
-    expect(env.PAPERCLIP_IN_WORKTREE).toBe("true");
     expect(formatShellExports(env)).toContain("export PAPERCLIP_INSTANCE_ID='feature-worktree-support'");
   });
 
@@ -201,205 +122,4 @@ describe("worktree helpers", () => {
     expect(full.excludedTables).toEqual([]);
     expect(full.nullifyColumns).toEqual({});
   });
-
-  it("copies the source local_encrypted secrets key into the seeded worktree instance", () => {
-    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-secrets-"));
-    const originalInlineMasterKey = process.env.PAPERCLIP_SECRETS_MASTER_KEY;
-    const originalKeyFile = process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
-    try {
-      delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
-      delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
-      const sourceConfigPath = path.join(tempRoot, "source", "config.json");
-      const sourceKeyPath = path.join(tempRoot, "source", "secrets", "master.key");
-      const targetKeyPath = path.join(tempRoot, "target", "secrets", "master.key");
-      fs.mkdirSync(path.dirname(sourceKeyPath), { recursive: true });
-      fs.writeFileSync(sourceKeyPath, "source-master-key", "utf8");
-
-      const sourceConfig = buildSourceConfig();
-      sourceConfig.secrets.localEncrypted.keyFilePath = sourceKeyPath;
-
-      copySeededSecretsKey({
-        sourceConfigPath,
-        sourceConfig,
-        sourceEnvEntries: {},
-        targetKeyFilePath: targetKeyPath,
-      });
-
-      expect(fs.readFileSync(targetKeyPath, "utf8")).toBe("source-master-key");
-    } finally {
-      if (originalInlineMasterKey === undefined) {
-        delete process.env.PAPERCLIP_SECRETS_MASTER_KEY;
-      } else {
-        process.env.PAPERCLIP_SECRETS_MASTER_KEY = originalInlineMasterKey;
-      }
-      if (originalKeyFile === undefined) {
-        delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;
-      } else {
-        process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE = originalKeyFile;
-      }
-      fs.rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-
-  it("writes the source inline secrets master key into the seeded worktree instance", () => {
-    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-secrets-"));
-    try {
-      const sourceConfigPath = path.join(tempRoot, "source", "config.json");
-      const targetKeyPath = path.join(tempRoot, "target", "secrets", "master.key");
-
-      copySeededSecretsKey({
-        sourceConfigPath,
-        sourceConfig: buildSourceConfig(),
-        sourceEnvEntries: {
-          PAPERCLIP_SECRETS_MASTER_KEY: "inline-source-master-key",
-        },
-        targetKeyFilePath: targetKeyPath,
-      });
-
-      expect(fs.readFileSync(targetKeyPath, "utf8")).toBe("inline-source-master-key");
-    } finally {
-      fs.rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-
-  it("persists the current agent jwt secret into the worktree env file", async () => {
-    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-jwt-"));
-    const repoRoot = path.join(tempRoot, "repo");
-    const originalCwd = process.cwd();
-    const originalJwtSecret = process.env.PAPERCLIP_AGENT_JWT_SECRET;
-
-    try {
-      fs.mkdirSync(repoRoot, { recursive: true });
-      process.env.PAPERCLIP_AGENT_JWT_SECRET = "worktree-shared-secret";
-      process.chdir(repoRoot);
-
-      await worktreeInitCommand({
-        seed: false,
-        fromConfig: path.join(tempRoot, "missing", "config.json"),
-        home: path.join(tempRoot, ".paperclip-worktrees"),
-      });
-
-      const envPath = path.join(repoRoot, ".paperclip", ".env");
-      expect(fs.readFileSync(envPath, "utf8")).toContain("PAPERCLIP_AGENT_JWT_SECRET=worktree-shared-secret");
-    } finally {
-      process.chdir(originalCwd);
-      if (originalJwtSecret === undefined) {
-        delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
-      } else {
-        process.env.PAPERCLIP_AGENT_JWT_SECRET = originalJwtSecret;
-      }
-      fs.rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-
-  it("rebinds same-repo workspace paths onto the current worktree root", () => {
-    expect(
-      rebindWorkspaceCwd({
-        sourceRepoRoot: "/Users/example/paperclip",
-        targetRepoRoot: "/Users/example/paperclip-pr-432",
-        workspaceCwd: "/Users/example/paperclip",
-      }),
-    ).toBe("/Users/example/paperclip-pr-432");
-
-    expect(
-      rebindWorkspaceCwd({
-        sourceRepoRoot: "/Users/example/paperclip",
-        targetRepoRoot: "/Users/example/paperclip-pr-432",
-        workspaceCwd: "/Users/example/paperclip/packages/db",
-      }),
-    ).toBe("/Users/example/paperclip-pr-432/packages/db");
-  });
-
-  it("does not rebind paths outside the source repo root", () => {
-    expect(
-      rebindWorkspaceCwd({
-        sourceRepoRoot: "/Users/example/paperclip",
-        targetRepoRoot: "/Users/example/paperclip-pr-432",
-        workspaceCwd: "/Users/example/other-project",
-      }),
-    ).toBeNull();
-  });
-
-  it("copies shared git hooks into a linked worktree git dir", () => {
-    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-hooks-"));
-    const repoRoot = path.join(tempRoot, "repo");
-    const worktreePath = path.join(tempRoot, "repo-feature");
-
-    try {
-      fs.mkdirSync(repoRoot, { recursive: true });
-      execFileSync("git", ["init"], { cwd: repoRoot, stdio: "ignore" });
-      execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: repoRoot, stdio: "ignore" });
-      execFileSync("git", ["config", "user.name", "Test User"], { cwd: repoRoot, stdio: "ignore" });
-      fs.writeFileSync(path.join(repoRoot, "README.md"), "# temp\n", "utf8");
-      execFileSync("git", ["add", "README.md"], { cwd: repoRoot, stdio: "ignore" });
-      execFileSync("git", ["commit", "-m", "Initial commit"], { cwd: repoRoot, stdio: "ignore" });
-
-      const sourceHooksDir = path.join(repoRoot, ".git", "hooks");
-      const sourceHookPath = path.join(sourceHooksDir, "pre-commit");
-      const sourceTokensPath = path.join(sourceHooksDir, "forbidden-tokens.txt");
-      fs.writeFileSync(sourceHookPath, "#!/usr/bin/env bash\nexit 0\n", { encoding: "utf8", mode: 0o755 });
-      fs.chmodSync(sourceHookPath, 0o755);
-      fs.writeFileSync(sourceTokensPath, "secret-token\n", "utf8");
-
-      execFileSync("git", ["worktree", "add", "--detach", worktreePath], { cwd: repoRoot, stdio: "ignore" });
-
-      const copied = copyGitHooksToWorktreeGitDir(worktreePath);
-      const worktreeGitDir = execFileSync("git", ["rev-parse", "--git-dir"], {
-        cwd: worktreePath,
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      }).trim();
-      const resolvedSourceHooksDir = fs.realpathSync(sourceHooksDir);
-      const resolvedTargetHooksDir = fs.realpathSync(path.resolve(worktreePath, worktreeGitDir, "hooks"));
-      const targetHookPath = path.join(resolvedTargetHooksDir, "pre-commit");
-      const targetTokensPath = path.join(resolvedTargetHooksDir, "forbidden-tokens.txt");
-
-      expect(copied).toMatchObject({
-        sourceHooksPath: resolvedSourceHooksDir,
-        targetHooksPath: resolvedTargetHooksDir,
-        copied: true,
-      });
-      expect(fs.readFileSync(targetHookPath, "utf8")).toBe("#!/usr/bin/env bash\nexit 0\n");
-      expect(fs.statSync(targetHookPath).mode & 0o111).not.toBe(0);
-      expect(fs.readFileSync(targetTokensPath, "utf8")).toBe("secret-token\n");
-    } finally {
-      execFileSync("git", ["worktree", "remove", "--force", worktreePath], { cwd: repoRoot, stdio: "ignore" });
-      fs.rmSync(tempRoot, { recursive: true, force: true });
-    }
-  });
-
-  it("creates and initializes a worktree from the top-level worktree:make command", async () => {
-    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-worktree-make-"));
-    const repoRoot = path.join(tempRoot, "repo");
-    const fakeHome = path.join(tempRoot, "home");
-    const worktreePath = path.join(fakeHome, "paperclip-make-test");
-    const originalCwd = process.cwd();
-    const homedirSpy = vi.spyOn(os, "homedir").mockReturnValue(fakeHome);
-
-    try {
-      fs.mkdirSync(repoRoot, { recursive: true });
-      fs.mkdirSync(fakeHome, { recursive: true });
-      execFileSync("git", ["init"], { cwd: repoRoot, stdio: "ignore" });
-      execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: repoRoot, stdio: "ignore" });
-      execFileSync("git", ["config", "user.name", "Test User"], { cwd: repoRoot, stdio: "ignore" });
-      fs.writeFileSync(path.join(repoRoot, "README.md"), "# temp\n", "utf8");
-      execFileSync("git", ["add", "README.md"], { cwd: repoRoot, stdio: "ignore" });
-      execFileSync("git", ["commit", "-m", "Initial commit"], { cwd: repoRoot, stdio: "ignore" });
-
-      process.chdir(repoRoot);
-
-      await worktreeMakeCommand("paperclip-make-test", {
-        seed: false,
-        home: path.join(tempRoot, ".paperclip-worktrees"),
-      });
-
-      expect(fs.existsSync(path.join(worktreePath, ".git"))).toBe(true);
-      expect(fs.existsSync(path.join(worktreePath, ".paperclip", "config.json"))).toBe(true);
-      expect(fs.existsSync(path.join(worktreePath, ".paperclip", ".env"))).toBe(true);
-    } finally {
-      process.chdir(originalCwd);
-      homedirSpy.mockRestore();
-      fs.rmSync(tempRoot, { recursive: true, force: true });
-    }
-  }, 20_000);
 });

cli/src/adapters/registry.ts

@@ -2,7 +2,6 @@ import type { CLIAdapterModule } from "@paperclipai/adapter-utils";
 import { printClaudeStreamEvent } from "@paperclipai/adapter-claude-local/cli";
 import { printCodexStreamEvent } from "@paperclipai/adapter-codex-local/cli";
 import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";
-import { printGeminiStreamEvent } from "@paperclipai/adapter-gemini-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";
@@ -34,11 +33,6 @@ const cursorLocalCLIAdapter: CLIAdapterModule = {
   formatStdoutEvent: printCursorStreamEvent,
 };
 
-const geminiLocalCLIAdapter: CLIAdapterModule = {
-  type: "gemini_local",
-  formatStdoutEvent: printGeminiStreamEvent,
-};
-
 const openclawGatewayCLIAdapter: CLIAdapterModule = {
   type: "openclaw_gateway",
   formatStdoutEvent: printOpenClawGatewayStreamEvent,
@@ -51,7 +45,6 @@ const adaptersByType = new Map<string, CLIAdapterModule>(
     openCodeLocalCLIAdapter,
     piLocalCLIAdapter,
     cursorLocalCLIAdapter,
-    geminiLocalCLIAdapter,
     openclawGatewayCLIAdapter,
     processCLIAdapter,
     httpCLIAdapter,

cli/src/commands/allowed-hostname.ts

@@ -26,9 +26,6 @@ export async function addAllowedHostname(host: string, opts: { config?: string }
     p.log.info(`Hostname ${pc.cyan(normalized)} is already allowed.`);
   } else {
     p.log.success(`Added allowed hostname: ${pc.cyan(normalized)}`);
-    p.log.message(
-      pc.dim("Restart the Paperclip server for this change to take effect."),
-    );
   }
 
   if (!(config.server.deploymentMode === "authenticated" && config.server.exposure === "private")) {

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

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

cli/src/commands/run.ts

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

cli/src/commands/worktree-lib.ts

@@ -202,7 +202,6 @@ export function buildWorktreeEnvEntries(paths: WorktreeLocalPaths): Record<strin
     PAPERCLIP_INSTANCE_ID: paths.instanceId,
     PAPERCLIP_CONFIG: paths.configPath,
     PAPERCLIP_CONTEXT: paths.contextPath,
-    PAPERCLIP_IN_WORKTREE: "true",
   };
 }
 

cli/src/commands/worktree.ts

@@ -1,29 +1,14 @@
-import {
-  chmodSync,
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  readlinkSync,
-  rmSync,
-  statSync,
-  symlinkSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { createServer } from "node:net";
 import * as p from "@clack/prompts";
 import pc from "picocolors";
-import { eq } from "drizzle-orm";
 import {
   applyPendingMigrations,
-  createDb,
   ensurePostgresDatabase,
   formatDatabaseBackupResult,
-  projectWorkspaces,
   runDatabaseBackup,
   runDatabaseRestore,
 } from "@paperclipai/db";
@@ -33,7 +18,6 @@ import { expandHomePrefix } from "../config/home.js";
 import type { PaperclipConfig } from "../config/schema.js";
 import { readConfig, resolveConfigPath, writeConfig } from "../config/store.js";
 import { printPaperclipCliBanner } from "../utils/banner.js";
-import { resolveRuntimeLikePath } from "../utils/path-resolver.js";
 import {
   buildWorktreeConfig,
   buildWorktreeEnvEntries,
@@ -62,10 +46,6 @@ type WorktreeInitOptions = {
   force?: boolean;
 };
 
-type WorktreeMakeOptions = WorktreeInitOptions & {
-  startPoint?: string;
-};
-
 type WorktreeEnvOptions = {
   config?: string;
   json?: boolean;
@@ -93,98 +73,10 @@ type EmbeddedPostgresHandle = {
   stop: () => Promise<void>;
 };
 
-type GitWorkspaceInfo = {
-  root: string;
-  commonDir: string;
-  gitDir: string;
-  hooksPath: string;
-};
-
-type CopiedGitHooksResult = {
-  sourceHooksPath: string;
-  targetHooksPath: string;
-  copied: boolean;
-};
-
-type SeedWorktreeDatabaseResult = {
-  backupSummary: string;
-  reboundWorkspaces: Array<{
-    name: string;
-    fromCwd: string;
-    toCwd: string;
-  }>;
-};
-
 function nonEmpty(value: string | null | undefined): string | null {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
 
-function isCurrentSourceConfigPath(sourceConfigPath: string): boolean {
-  const currentConfigPath = process.env.PAPERCLIP_CONFIG;
-  if (!currentConfigPath || currentConfigPath.trim().length === 0) {
-    return false;
-  }
-  return path.resolve(currentConfigPath) === path.resolve(sourceConfigPath);
-}
-
-function resolveWorktreeMakeName(name: string): string {
-  const value = nonEmpty(name);
-  if (!value) {
-    throw new Error("Worktree name is required.");
-  }
-  if (!/^[A-Za-z0-9._-]+$/.test(value)) {
-    throw new Error(
-      "Worktree name must contain only letters, numbers, dots, underscores, or dashes.",
-    );
-  }
-  return value;
-}
-
-export function resolveWorktreeMakeTargetPath(name: string): string {
-  return path.resolve(os.homedir(), resolveWorktreeMakeName(name));
-}
-
-function extractExecSyncErrorMessage(error: unknown): string | null {
-  if (!error || typeof error !== "object") {
-    return error instanceof Error ? error.message : null;
-  }
-
-  const stderr = "stderr" in error ? error.stderr : null;
-  if (typeof stderr === "string") {
-    return nonEmpty(stderr);
-  }
-  if (stderr instanceof Buffer) {
-    return nonEmpty(stderr.toString("utf8"));
-  }
-
-  return error instanceof Error ? nonEmpty(error.message) : null;
-}
-
-function localBranchExists(cwd: string, branchName: string): boolean {
-  try {
-    execFileSync("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branchName}`], {
-      cwd,
-      stdio: "ignore",
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export function resolveGitWorktreeAddArgs(input: {
-  branchName: string;
-  targetPath: string;
-  branchExists: boolean;
-  startPoint?: string;
-}): string[] {
-  if (input.branchExists && !input.startPoint) {
-    return ["worktree", "add", input.targetPath, input.branchName];
-  }
-  const commitish = input.startPoint ?? "HEAD";
-  return ["worktree", "add", "-b", input.branchName, input.targetPath, commitish];
-}
-
 function readPidFilePort(postmasterPidFile: string): number | null {
   if (!existsSync(postmasterPidFile)) return null;
   try {
@@ -240,180 +132,6 @@ function detectGitBranchName(cwd: string): string | null {
   }
 }
 
-function detectGitWorkspaceInfo(cwd: string): GitWorkspaceInfo | null {
-  try {
-    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
-      cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    const commonDirRaw = execFileSync("git", ["rev-parse", "--git-common-dir"], {
-      cwd: root,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    const gitDirRaw = execFileSync("git", ["rev-parse", "--git-dir"], {
-      cwd: root,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    const hooksPathRaw = execFileSync("git", ["rev-parse", "--git-path", "hooks"], {
-      cwd: root,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    return {
-      root: path.resolve(root),
-      commonDir: path.resolve(root, commonDirRaw),
-      gitDir: path.resolve(root, gitDirRaw),
-      hooksPath: path.resolve(root, hooksPathRaw),
-    };
-  } catch {
-    return null;
-  }
-}
-
-function copyDirectoryContents(sourceDir: string, targetDir: string): boolean {
-  if (!existsSync(sourceDir)) return false;
-
-  const entries = readdirSync(sourceDir, { withFileTypes: true });
-  if (entries.length === 0) return false;
-
-  mkdirSync(targetDir, { recursive: true });
-
-  let copied = false;
-  for (const entry of entries) {
-    const sourcePath = path.resolve(sourceDir, entry.name);
-    const targetPath = path.resolve(targetDir, entry.name);
-
-    if (entry.isDirectory()) {
-      mkdirSync(targetPath, { recursive: true });
-      copyDirectoryContents(sourcePath, targetPath);
-      copied = true;
-      continue;
-    }
-
-    if (entry.isSymbolicLink()) {
-      rmSync(targetPath, { recursive: true, force: true });
-      symlinkSync(readlinkSync(sourcePath), targetPath);
-      copied = true;
-      continue;
-    }
-
-    copyFileSync(sourcePath, targetPath);
-    try {
-      chmodSync(targetPath, statSync(sourcePath).mode & 0o777);
-    } catch {
-      // best effort
-    }
-    copied = true;
-  }
-
-  return copied;
-}
-
-export function copyGitHooksToWorktreeGitDir(cwd: string): CopiedGitHooksResult | null {
-  const workspace = detectGitWorkspaceInfo(cwd);
-  if (!workspace) return null;
-
-  const sourceHooksPath = workspace.hooksPath;
-  const targetHooksPath = path.resolve(workspace.gitDir, "hooks");
-
-  if (sourceHooksPath === targetHooksPath) {
-    return {
-      sourceHooksPath,
-      targetHooksPath,
-      copied: false,
-    };
-  }
-
-  return {
-    sourceHooksPath,
-    targetHooksPath,
-    copied: copyDirectoryContents(sourceHooksPath, targetHooksPath),
-  };
-}
-
-export function rebindWorkspaceCwd(input: {
-  sourceRepoRoot: string;
-  targetRepoRoot: string;
-  workspaceCwd: string;
-}): string | null {
-  const sourceRepoRoot = path.resolve(input.sourceRepoRoot);
-  const targetRepoRoot = path.resolve(input.targetRepoRoot);
-  const workspaceCwd = path.resolve(input.workspaceCwd);
-  const relative = path.relative(sourceRepoRoot, workspaceCwd);
-  if (!relative || relative === "") {
-    return targetRepoRoot;
-  }
-  if (relative.startsWith("..") || path.isAbsolute(relative)) {
-    return null;
-  }
-  return path.resolve(targetRepoRoot, relative);
-}
-
-async function rebindSeededProjectWorkspaces(input: {
-  targetConnectionString: string;
-  currentCwd: string;
-}): Promise<SeedWorktreeDatabaseResult["reboundWorkspaces"]> {
-  const targetRepo = detectGitWorkspaceInfo(input.currentCwd);
-  if (!targetRepo) return [];
-
-  const db = createDb(input.targetConnectionString);
-  const closableDb = db as typeof db & {
-    $client?: { end?: (opts?: { timeout?: number }) => Promise<void> };
-  };
-
-  try {
-    const rows = await db
-      .select({
-        id: projectWorkspaces.id,
-        name: projectWorkspaces.name,
-        cwd: projectWorkspaces.cwd,
-      })
-      .from(projectWorkspaces);
-
-    const rebound: SeedWorktreeDatabaseResult["reboundWorkspaces"] = [];
-    for (const row of rows) {
-      const workspaceCwd = nonEmpty(row.cwd);
-      if (!workspaceCwd) continue;
-
-      const sourceRepo = detectGitWorkspaceInfo(workspaceCwd);
-      if (!sourceRepo) continue;
-      if (sourceRepo.commonDir !== targetRepo.commonDir) continue;
-
-      const reboundCwd = rebindWorkspaceCwd({
-        sourceRepoRoot: sourceRepo.root,
-        targetRepoRoot: targetRepo.root,
-        workspaceCwd,
-      });
-      if (!reboundCwd) continue;
-
-      const normalizedCurrent = path.resolve(workspaceCwd);
-      if (reboundCwd === normalizedCurrent) continue;
-      if (!existsSync(reboundCwd)) continue;
-
-      await db
-        .update(projectWorkspaces)
-        .set({
-          cwd: reboundCwd,
-          updatedAt: new Date(),
-        })
-        .where(eq(projectWorkspaces.id, row.id));
-
-      rebound.push({
-        name: row.name,
-        fromCwd: normalizedCurrent,
-        toCwd: reboundCwd,
-      });
-    }
-
-    return rebound;
-  } finally {
-    await closableDb.$client?.end?.({ timeout: 5 }).catch(() => undefined);
-  }
-}
-
 function resolveSourceConfigPath(opts: WorktreeInitOptions): string {
   if (opts.fromConfig) return path.resolve(opts.fromConfig);
   const sourceHome = path.resolve(expandHomePrefix(opts.fromDataDir ?? "~/.paperclip"));
@@ -436,55 +154,6 @@ function resolveSourceConnectionString(config: PaperclipConfig, envEntries: Reco
   return `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
 }
 
-export function copySeededSecretsKey(input: {
-  sourceConfigPath: string;
-  sourceConfig: PaperclipConfig;
-  sourceEnvEntries: Record<string, string>;
-  targetKeyFilePath: string;
-}): void {
-  if (input.sourceConfig.secrets.provider !== "local_encrypted") {
-    return;
-  }
-
-  mkdirSync(path.dirname(input.targetKeyFilePath), { recursive: true });
-
-  const allowProcessEnvFallback = isCurrentSourceConfigPath(input.sourceConfigPath);
-  const sourceInlineMasterKey =
-    nonEmpty(input.sourceEnvEntries.PAPERCLIP_SECRETS_MASTER_KEY) ??
-    (allowProcessEnvFallback ? nonEmpty(process.env.PAPERCLIP_SECRETS_MASTER_KEY) : null);
-  if (sourceInlineMasterKey) {
-    writeFileSync(input.targetKeyFilePath, sourceInlineMasterKey, {
-      encoding: "utf8",
-      mode: 0o600,
-    });
-    try {
-      chmodSync(input.targetKeyFilePath, 0o600);
-    } catch {
-      // best effort
-    }
-    return;
-  }
-
-  const sourceKeyFileOverride =
-    nonEmpty(input.sourceEnvEntries.PAPERCLIP_SECRETS_MASTER_KEY_FILE) ??
-    (allowProcessEnvFallback ? nonEmpty(process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE) : null);
-  const sourceConfiguredKeyPath = sourceKeyFileOverride ?? input.sourceConfig.secrets.localEncrypted.keyFilePath;
-  const sourceKeyFilePath = resolveRuntimeLikePath(sourceConfiguredKeyPath, input.sourceConfigPath);
-
-  if (!existsSync(sourceKeyFilePath)) {
-    throw new Error(
-      `Cannot seed worktree database because source local_encrypted secrets key was not found at ${sourceKeyFilePath}.`,
-    );
-  }
-
-  copyFileSync(sourceKeyFilePath, input.targetKeyFilePath);
-  try {
-    chmodSync(input.targetKeyFilePath, 0o600);
-  } catch {
-    // best effort
-  }
-}
-
 async function ensureEmbeddedPostgres(dataDir: string, preferredPort: number): Promise<EmbeddedPostgresHandle> {
   const moduleName = "embedded-postgres";
   let EmbeddedPostgres: EmbeddedPostgresCtor;
@@ -542,16 +211,10 @@ async function seedWorktreeDatabase(input: {
   targetPaths: WorktreeLocalPaths;
   instanceId: string;
   seedMode: WorktreeSeedMode;
-}): Promise<SeedWorktreeDatabaseResult> {
+}): Promise<string> {
   const seedPlan = resolveWorktreeSeedPlan(input.seedMode);
   const sourceEnvFile = resolvePaperclipEnvFile(input.sourceConfigPath);
   const sourceEnvEntries = readPaperclipEnvEntries(sourceEnvFile);
-  copySeededSecretsKey({
-    sourceConfigPath: input.sourceConfigPath,
-    sourceConfig: input.sourceConfig,
-    sourceEnvEntries,
-    targetKeyFilePath: input.targetPaths.secretsKeyFilePath,
-  });
   let sourceHandle: EmbeddedPostgresHandle | null = null;
   let targetHandle: EmbeddedPostgresHandle | null = null;
 
@@ -590,15 +253,8 @@ async function seedWorktreeDatabase(input: {
       backupFile: backup.backupFile,
     });
     await applyPendingMigrations(targetConnectionString);
-    const reboundWorkspaces = await rebindSeededProjectWorkspaces({
-      targetConnectionString,
-      currentCwd: input.targetPaths.cwd,
-    });
 
-    return {
-      backupSummary: formatDatabaseBackupResult(backup),
-      reboundWorkspaces,
-    };
+    return formatDatabaseBackupResult(backup);
   } finally {
     if (targetHandle?.startedByThisProcess) {
       await targetHandle.stop();
@@ -609,7 +265,10 @@ async function seedWorktreeDatabase(input: {
   }
 }
 
-async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
+export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<void> {
+  printPaperclipCliBanner();
+  p.intro(pc.bgCyan(pc.black(" paperclipai worktree init ")));
+
   const cwd = process.cwd();
   const name = resolveSuggestedWorktreeName(
     cwd,
@@ -651,23 +310,11 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
   });
 
   writeConfig(targetConfig, paths.configPath);
-  const sourceEnvEntries = readPaperclipEnvEntries(resolvePaperclipEnvFile(sourceConfigPath));
-  const existingAgentJwtSecret =
-    nonEmpty(sourceEnvEntries.PAPERCLIP_AGENT_JWT_SECRET) ??
-    nonEmpty(process.env.PAPERCLIP_AGENT_JWT_SECRET);
-  mergePaperclipEnvEntries(
-    {
-      ...buildWorktreeEnvEntries(paths),
-      ...(existingAgentJwtSecret ? { PAPERCLIP_AGENT_JWT_SECRET: existingAgentJwtSecret } : {}),
-    },
-    paths.envPath,
-  );
+  mergePaperclipEnvEntries(buildWorktreeEnvEntries(paths), paths.envPath);
   ensureAgentJwtSecret(paths.configPath);
   loadPaperclipEnvFile(paths.configPath);
-  const copiedGitHooks = copyGitHooksToWorktreeGitDir(cwd);
 
   let seedSummary: string | null = null;
-  let reboundWorkspaceSummary: SeedWorktreeDatabaseResult["reboundWorkspaces"] = [];
   if (opts.seed !== false) {
     if (!sourceConfig) {
       throw new Error(
@@ -677,7 +324,7 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
     const spinner = p.spinner();
     spinner.start(`Seeding isolated worktree database from source instance (${seedMode})...`);
     try {
-      const seeded = await seedWorktreeDatabase({
+      seedSummary = await seedWorktreeDatabase({
         sourceConfigPath,
         sourceConfig,
         targetConfig,
@@ -685,8 +332,6 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
         instanceId,
         seedMode,
       });
-      seedSummary = seeded.backupSummary;
-      reboundWorkspaceSummary = seeded.reboundWorkspaces;
       spinner.stop(`Seeded isolated worktree database (${seedMode}).`);
     } catch (error) {
       spinner.stop(pc.red("Failed to seed worktree database."));
@@ -699,19 +344,9 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
   p.log.message(pc.dim(`Isolated home: ${paths.homeDir}`));
   p.log.message(pc.dim(`Instance: ${paths.instanceId}`));
   p.log.message(pc.dim(`Server port: ${serverPort} | DB port: ${databasePort}`));
-  if (copiedGitHooks?.copied) {
-    p.log.message(
-      pc.dim(`Mirrored git hooks: ${copiedGitHooks.sourceHooksPath} -> ${copiedGitHooks.targetHooksPath}`),
-    );
-  }
   if (seedSummary) {
     p.log.message(pc.dim(`Seed mode: ${seedMode}`));
     p.log.message(pc.dim(`Seed snapshot: ${seedSummary}`));
-    for (const rebound of reboundWorkspaceSummary) {
-      p.log.message(
-        pc.dim(`Rebound workspace ${rebound.name}: ${rebound.fromCwd} -> ${rebound.toCwd}`),
-      );
-    }
   }
   p.outro(
     pc.green(
@@ -720,85 +355,6 @@ async function runWorktreeInit(opts: WorktreeInitOptions): Promise<void> {
   );
 }
 
-export async function worktreeInitCommand(opts: WorktreeInitOptions): Promise<void> {
-  printPaperclipCliBanner();
-  p.intro(pc.bgCyan(pc.black(" paperclipai worktree init ")));
-  await runWorktreeInit(opts);
-}
-
-export async function worktreeMakeCommand(nameArg: string, opts: WorktreeMakeOptions): Promise<void> {
-  printPaperclipCliBanner();
-  p.intro(pc.bgCyan(pc.black(" paperclipai worktree:make ")));
-
-  const name = resolveWorktreeMakeName(nameArg);
-  const sourceCwd = process.cwd();
-  const targetPath = resolveWorktreeMakeTargetPath(name);
-  if (existsSync(targetPath)) {
-    throw new Error(`Target path already exists: ${targetPath}`);
-  }
-
-  mkdirSync(path.dirname(targetPath), { recursive: true });
-  if (opts.startPoint) {
-    const [remote] = opts.startPoint.split("/", 1);
-    try {
-      execFileSync("git", ["fetch", remote], {
-        cwd: sourceCwd,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-    } catch (error) {
-      throw new Error(
-        `Failed to fetch from remote "${remote}": ${extractExecSyncErrorMessage(error) ?? String(error)}`,
-      );
-    }
-  }
-
-  const worktreeArgs = resolveGitWorktreeAddArgs({
-    branchName: name,
-    targetPath,
-    branchExists: !opts.startPoint && localBranchExists(sourceCwd, name),
-    startPoint: opts.startPoint,
-  });
-
-  const spinner = p.spinner();
-  spinner.start(`Creating git worktree at ${targetPath}...`);
-  try {
-    execFileSync("git", worktreeArgs, {
-      cwd: sourceCwd,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    spinner.stop(`Created git worktree at ${targetPath}.`);
-  } catch (error) {
-    spinner.stop(pc.red("Failed to create git worktree."));
-    throw new Error(extractExecSyncErrorMessage(error) ?? String(error));
-  }
-
-  const installSpinner = p.spinner();
-  installSpinner.start("Installing dependencies...");
-  try {
-    execFileSync("pnpm", ["install"], {
-      cwd: targetPath,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    installSpinner.stop("Installed dependencies.");
-  } catch (error) {
-    installSpinner.stop(pc.yellow("Failed to install dependencies (continuing anyway)."));
-    p.log.warning(extractExecSyncErrorMessage(error) ?? String(error));
-  }
-
-  const originalCwd = process.cwd();
-  try {
-    process.chdir(targetPath);
-    await runWorktreeInit({
-      ...opts,
-      name,
-    });
-  } catch (error) {
-    throw error;
-  } finally {
-    process.chdir(originalCwd);
-  }
-}
-
 export async function worktreeEnvCommand(opts: WorktreeEnvOptions): Promise<void> {
   const configPath = resolveConfigPath(opts.config);
   const envPath = resolvePaperclipEnvFile(configPath);
@@ -822,23 +378,6 @@ export async function worktreeEnvCommand(opts: WorktreeEnvOptions): Promise<void
 export function registerWorktreeCommands(program: Command): void {
   const worktree = program.command("worktree").description("Worktree-local Paperclip instance helpers");
 
-  program
-    .command("worktree:make")
-    .description("Create ~/NAME as a git worktree, then initialize an isolated Paperclip instance inside it")
-    .argument("<name>", "Worktree directory and branch name (created at ~/NAME)")
-    .option("--start-point <ref>", "Remote ref to base the new branch on (e.g. origin/main)")
-    .option("--instance <id>", "Explicit isolated instance id")
-    .option("--home <path>", `Home root for worktree instances (default: ${DEFAULT_WORKTREE_HOME})`)
-    .option("--from-config <path>", "Source config.json to seed from")
-    .option("--from-data-dir <path>", "Source PAPERCLIP_HOME used when deriving the source config")
-    .option("--from-instance <id>", "Source instance id when deriving the source config", "default")
-    .option("--server-port <port>", "Preferred server port", (value) => Number(value))
-    .option("--db-port <port>", "Preferred embedded Postgres port", (value) => Number(value))
-    .option("--seed-mode <mode>", "Seed profile: minimal or full (default: minimal)", "minimal")
-    .option("--no-seed", "Skip database seeding from the source instance")
-    .option("--force", "Replace existing repo-local config and isolated instance data", false)
-    .action(worktreeMakeCommand);
-
   worktree
     .command("init")
     .description("Create repo-local config/env and an isolated instance for this worktree")

cli/src/prompts/server.ts

@@ -162,3 +162,4 @@ export async function promptServer(opts?: {
     auth,
   };
 }
+

cli/tsconfig.json

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

doc/DATABASE.md

@@ -19,14 +19,6 @@ That's it. On first start the server:
 
 Data persists across restarts in `~/.paperclip/instances/default/db/`. To reset local dev data, delete that directory.
 
-If you need to apply pending migrations manually, run:
-
-```sh
-pnpm db:migrate
-```
-
-When `DATABASE_URL` is unset, this command targets the current embedded PostgreSQL instance for your active Paperclip config/instance.
-
 This mode is ideal for local development and one-command installs.
 
 Docker note: the Docker quickstart image also uses embedded PostgreSQL by default. Persist `/paperclip` to keep DB state across container restarts (see `doc/DOCKER.md`).

doc/DEVELOPING.md

@@ -19,9 +19,9 @@ Current implementation status:
 
 GitHub Actions owns `pnpm-lock.yaml`.
 
-- Same-repo pull requests that change dependency manifests are auto-refreshed by GitHub Actions before merge.
-- Fork pull requests that change dependency manifests must include the refreshed `pnpm-lock.yaml`.
-- Pull request CI validates lockfile freshness when manifests change and verifies with `--frozen-lockfile`.
+- Do not commit `pnpm-lock.yaml` in pull requests.
+- Pull request CI validates dependency resolution when manifests change.
+- Pushes to `master` regenerate `pnpm-lock.yaml` with `pnpm install --lockfile-only --no-frozen-lockfile`, commit it back if needed, and then run verification with `--frozen-lockfile`.
 
 ## Start Dev
 
@@ -132,15 +132,12 @@ Instead, create a repo-local Paperclip config plus an isolated instance for the
 
 ```sh
 paperclipai worktree init
-# or create the git worktree and initialize it in one step:
-pnpm paperclipai worktree:make paperclip-pr-432
 ```
 
 This command:
 
 - writes repo-local files at `.paperclip/config.json` and `.paperclip/.env`
 - creates an isolated instance under `~/.paperclip-worktrees/instances/<worktree-id>/`
-- when run inside a linked git worktree, mirrors the effective git hooks into that worktree's private git dir
 - picks a free app port and embedded PostgreSQL port
 - by default seeds the isolated DB in `minimal` mode from your main instance via a logical SQL snapshot
 
@@ -152,8 +149,6 @@ Seed modes:
 
 After `worktree init`, both the server and the CLI auto-load the repo-local `.paperclip/.env` when run inside that worktree, so normal commands like `pnpm dev`, `paperclipai doctor`, and `paperclipai db:backup` stay scoped to the worktree instance.
 
-That repo-local env also sets `PAPERCLIP_IN_WORKTREE=true`, which the server can use for worktree-specific UI behavior such as an alternate favicon.
-
 Print shell exports explicitly when needed:
 
 ```sh
@@ -162,75 +157,17 @@ paperclipai worktree env
 eval "$(paperclipai worktree env)"
 ```
 
-### Worktree CLI Reference
-
-**`pnpm paperclipai worktree init [options]`** — Create repo-local config/env and an isolated instance for the current worktree.
-
-| Option | Description |
-|---|---|
-| `--name <name>` | Display name used to derive the instance id |
-| `--instance <id>` | Explicit isolated instance id |
-| `--home <path>` | Home root for worktree instances (default: `~/.paperclip-worktrees`) |
-| `--from-config <path>` | Source config.json to seed from |
-| `--from-data-dir <path>` | Source PAPERCLIP_HOME used when deriving the source config |
-| `--from-instance <id>` | Source instance id (default: `default`) |
-| `--server-port <port>` | Preferred server port |
-| `--db-port <port>` | Preferred embedded Postgres port |
-| `--seed-mode <mode>` | Seed profile: `minimal` or `full` (default: `minimal`) |
-| `--no-seed` | Skip database seeding from the source instance |
-| `--force` | Replace existing repo-local config and isolated instance data |
-
-Examples:
+Useful options:
 
 ```sh
 paperclipai worktree init --no-seed
+paperclipai worktree init --seed-mode minimal
 paperclipai worktree init --seed-mode full
 paperclipai worktree init --from-instance default
 paperclipai worktree init --from-data-dir ~/.paperclip
 paperclipai worktree init --force
 ```
 
-**`pnpm paperclipai worktree:make <name> [options]`** — Create `~/NAME` as a git worktree, then initialize an isolated Paperclip instance inside it. This combines `git worktree add` with `worktree init` in a single step.
-
-| Option | Description |
-|---|---|
-| `--start-point <ref>` | Remote ref to base the new branch on (e.g. `origin/main`) |
-| `--instance <id>` | Explicit isolated instance id |
-| `--home <path>` | Home root for worktree instances (default: `~/.paperclip-worktrees`) |
-| `--from-config <path>` | Source config.json to seed from |
-| `--from-data-dir <path>` | Source PAPERCLIP_HOME used when deriving the source config |
-| `--from-instance <id>` | Source instance id (default: `default`) |
-| `--server-port <port>` | Preferred server port |
-| `--db-port <port>` | Preferred embedded Postgres port |
-| `--seed-mode <mode>` | Seed profile: `minimal` or `full` (default: `minimal`) |
-| `--no-seed` | Skip database seeding from the source instance |
-| `--force` | Replace existing repo-local config and isolated instance data |
-
-Examples:
-
-```sh
-pnpm paperclipai worktree:make paperclip-pr-432
-pnpm paperclipai worktree:make my-feature --start-point origin/main
-pnpm paperclipai worktree:make experiment --no-seed
-```
-
-**`pnpm paperclipai worktree env [options]`** — Print shell exports for the current worktree-local Paperclip instance.
-
-| Option | Description |
-|---|---|
-| `-c, --config <path>` | Path to config file |
-| `--json` | Print JSON instead of shell exports |
-
-Examples:
-
-```sh
-pnpm paperclipai worktree env
-pnpm paperclipai worktree env --json
-eval "$(pnpm paperclipai worktree env)"
-```
-
-For project execution worktrees, Paperclip can also run a project-defined provision command after it creates or reuses an isolated git worktree. Configure this on the project's execution workspace policy (`workspaceStrategy.provisionCommand`). The command runs inside the derived worktree and receives `PAPERCLIP_WORKSPACE_*`, `PAPERCLIP_PROJECT_ID`, `PAPERCLIP_AGENT_ID`, and `PAPERCLIP_ISSUE_*` environment variables so each repo can bootstrap itself however it wants.
-
 ## Quick Health Checks
 
 In another terminal:

doc/DOCKER.md

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

doc/PUBLISHING.md

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

doc/RELEASING.md

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

doc/SPEC-implementation.md

@@ -37,7 +37,7 @@ These decisions close open questions from `SPEC.md` for V1.
 | Visibility | Full visibility to board and all agents in same company |
 | Communication | Tasks + comments only (no separate chat system) |
 | Task ownership | Single assignee; atomic checkout required for `in_progress` transition |
-| Recovery | No automatic reassignment; work recovery stays manual/explicit |
+| Recovery | No automatic reassignment; stale work is surfaced, not silently fixed |
 | Agent adapters | Built-in `process` and `http` adapters |
 | Auth | Mode-dependent human auth (`local_trusted` implicit board in current code; authenticated mode uses sessions), API keys for agents |
 | Budget period | Monthly UTC calendar window |
@@ -106,6 +106,7 @@ A lightweight scheduler/worker in the server process handles:
 - heartbeat trigger checks
 - stuck run detection
 - budget threshold checks
+- stale task reporting generation
 
 Separate queue infrastructure is not required for V1.
 
@@ -501,6 +502,7 @@ Dashboard payload must include:
 - open/in-progress/blocked/done issue counts
 - month-to-date spend and budget utilization
 - pending approvals count
+- stale task count
 
 ## 10.9 Error Semantics
 
@@ -679,6 +681,7 @@ Required UX behaviors:
 - global company selector
 - quick actions: pause/resume agent, create task, approve/reject request
 - conflict toasts on atomic checkout failure
+- clear stale-task indicators
 - no silent background failures; every failed run visible in UI
 
 ## 15. Operational Requirements
@@ -777,6 +780,7 @@ A release candidate is blocked unless these pass:
 
 - add company selector and org chart view
 - add approvals and cost pages
+- add operational dashboard and stale-task surfacing
 
 ## Milestone 6: Hardening and Release
 

doc/experimental/issue-worktree-support.md

@@ -1,62 +0,0 @@
-# Issue worktree support
-
-Status: experimental, runtime-only, not shipping as a user-facing feature yet.
-
-This branch contains the runtime and seeding work needed for issue-scoped worktrees:
-
-- project execution workspace policy support
-- issue-level execution workspace settings
-- git worktree realization for isolated issue execution
-- optional command-based worktree provisioning
-- seeded worktree fixes for secrets key compatibility
-- seeded project workspace rebinding to the current git worktree
-
-We are intentionally not shipping the UI for this yet. The runtime code remains in place, but the main UI entrypoints are hard-gated off for now.
-
-## What works today
-
-- projects can carry execution workspace policy in the backend
-- issues can carry execution workspace settings in the backend
-- heartbeat execution can realize isolated git worktrees
-- runtime can run a project-defined provision command inside the derived worktree
-- seeded worktree instances can keep local-encrypted secrets working
-- seeded worktree instances can rebind same-repo project workspace paths onto the current git worktree
-
-## Hidden UI entrypoints
-
-These are the current user-facing UI surfaces for the feature, now intentionally disabled:
-
-- project settings:
-  - `ui/src/components/ProjectProperties.tsx`
-  - execution workspace policy controls
-  - git worktree base ref / branch template / parent dir
-  - provision / teardown command inputs
-
-- issue creation:
-  - `ui/src/components/NewIssueDialog.tsx`
-  - isolated issue checkout toggle
-  - defaulting issue execution workspace settings from project policy
-
-- issue editing:
-  - `ui/src/components/IssueProperties.tsx`
-  - issue-level workspace mode toggle
-  - defaulting issue execution workspace settings when project changes
-
-- agent/runtime settings:
-  - `ui/src/adapters/runtime-json-fields.tsx`
-  - runtime services JSON field, which is part of the broader workspace-runtime support surface
-
-## Why the UI is hidden
-
-- the runtime behavior is still being validated
-- the workflow and operator ergonomics are not final
-- we do not want to expose a partially-baked user-facing feature in issues, projects, or settings
-
-## Re-enable plan
-
-When this is ready to ship:
-
-- re-enable the gated UI sections in the files above
-- review wording and defaults for project and issue controls
-- decide which agent/runtime settings should remain advanced-only
-- add end-to-end product-level verification for the full UI workflow

doc/plans/agent-chat-ui-and-issue-backed-conversations.md

@@ -1,329 +0,0 @@
-# Agent Chat UI and Issue-Backed Conversations
-
-## Context
-
-`PAP-475` asks two related questions:
-
-1. What UI kit should Paperclip use if we add a chat surface with an agent?
-2. How should chat fit the product without breaking the current issue-centric model?
-
-This is not only a component-library decision. In Paperclip today:
-
-- V1 explicitly says communication is `tasks + comments only`, with no separate chat system.
-- Issues already carry assignment, audit trail, billing code, project linkage, goal linkage, and active run linkage.
-- Live run streaming already exists on issue detail pages.
-- Agent sessions already persist by `taskKey`, and today `taskKey` falls back to `issueId`.
-- The OpenClaw gateway adapter already supports an issue-scoped session key strategy.
-
-That means the cheapest useful path is not "add a second messaging product inside Paperclip." It is "add a better conversational UI on top of issue and run primitives we already have."
-
-## Current Constraints From the Codebase
-
-### Durable work object
-
-The durable object in Paperclip is the issue, not a chat thread.
-
-- `IssueDetail` already combines comments, linked runs, live runs, and activity into one timeline.
-- `CommentThread` already renders markdown comments and supports reply/reassignment flows.
-- `LiveRunWidget` already renders streaming assistant/tool/system output for active runs.
-
-### Session behavior
-
-Session continuity is already task-shaped.
-
-- `heartbeat.ts` derives `taskKey` from `taskKey`, then `taskId`, then `issueId`.
-- `agent_task_sessions` stores session state per company + agent + adapter + task key.
-- OpenClaw gateway supports `sessionKeyStrategy=issue|fixed|run`, and `issue` already matches the Paperclip mental model well.
-
-That means "chat with the CEO about this issue" naturally maps to one durable session per issue today without inventing a second session system.
-
-### Billing behavior
-
-Billing is already issue-aware.
-
-- `cost_events` can attach to `issueId`, `projectId`, `goalId`, and `billingCode`.
-- heartbeat context already propagates issue linkage into runs and cost rollups.
-
-If chat leaves the issue model, Paperclip would need a second billing story. That is avoidable.
-
-## UI Kit Recommendation
-
-## Recommendation: `assistant-ui`
-
-Use `assistant-ui` as the chat presentation layer.
-
-Why it fits Paperclip:
-
-- It is a real chat UI kit, not just a hook.
-- It is composable and aligned with shadcn-style primitives, which matches the current UI stack well.
-- It explicitly supports custom backends, which matters because Paperclip talks to agents through issue comments, heartbeats, and run streams rather than direct provider calls.
-- It gives us polished chat affordances quickly: message list, composer, streaming text, attachments, thread affordances, and markdown-oriented rendering.
-
-Why not make "the Vercel one" the primary choice:
-
-- Vercel AI SDK is stronger today than the older "just `useChat` over `/api/chat`" framing. Its transport layer is flexible and can support custom protocols.
-- But AI SDK is still better understood here as a transport/runtime protocol layer than as the best end-user chat surface for Paperclip.
-- Paperclip does not need Vercel to own message state, persistence, or the backend contract. Paperclip already has its own issue, run, and session model.
-
-So the clean split is:
-
-- `assistant-ui` for UI primitives
-- Paperclip-owned runtime/store for state, persistence, and transport
-- optional AI SDK usage later only if we want its stream protocol or client transport abstraction
-
-## Product Options
-
-### Option A: Separate chat object
-
-Create a new top-level chat/thread model unrelated to issues.
-
-Pros:
-
-- clean mental model if users want freeform conversation
-- easy to hide from issue boards
-
-Cons:
-
-- breaks the current V1 product decision that communication is issue-centric
-- needs new persistence, billing, session, permissions, activity, and wakeup rules
-- creates a second "why does this exist?" object beside issues
-- makes "pick up an old chat" a separate retrieval problem
-
-Verdict: not recommended for V1.
-
-### Option B: Every chat is an issue
-
-Treat chat as a UI mode over an issue. The issue remains the durable record.
-
-Pros:
-
-- matches current product spec
-- billing, runs, comments, approvals, and activity already work
-- sessions already resume on issue identity
-- works with all adapters, including OpenClaw, without new agent auth or a second API surface
-
-Cons:
-
-- some chats are not really "tasks" in a board sense
-- onboarding and review conversations may clutter normal issue lists
-
-Verdict: best V1 foundation.
-
-### Option C: Hybrid with hidden conversation issues
-
-Back every conversation with an issue, but allow a conversation-flavored issue mode that is hidden from default execution boards unless promoted.
-
-Pros:
-
-- preserves the issue-centric backend
-- gives onboarding/review chat a cleaner UX
-- preserves billing and session continuity
-
-Cons:
-
-- requires extra UI rules and possibly a small schema or filtering addition
-- can become a disguised second system if not kept narrow
-
-Verdict: likely the right product shape after a basic issue-backed MVP.
-
-## Recommended Product Model
-
-### Phase 1 product decision
-
-For the first implementation, chat should be issue-backed.
-
-More specifically:
-
-- the board opens a chat surface for an issue
-- sending a message is a comment mutation on that issue
-- the assigned agent is woken through the existing issue-comment flow
-- streaming output comes from the existing live run stream for that issue
-- durable assistant output remains comments and run history, not an extra transcript store
-
-This keeps Paperclip honest about what it is:
-
-- the control plane stays issue-centric
-- chat is a better way to interact with issue work, not a new collaboration product
-
-### Onboarding and CEO conversations
-
-For onboarding, weekly reviews, and "chat with the CEO", use a conversation issue rather than a global chat tab.
-
-Suggested shape:
-
-- create a board-initiated issue assigned to the CEO
-- mark it as conversation-flavored in UI treatment
-- optionally hide it from normal issue boards by default later
-- keep all cost/run/session linkage on that issue
-
-This solves several concerns at once:
-
-- no separate API key or direct provider wiring is needed
-- the same CEO adapter is used
-- old conversations are recovered through normal issue history
-- the CEO can still create or update real child issues from the conversation
-
-## Session Model
-
-### V1
-
-Use one durable conversation session per issue.
-
-That already matches current behavior:
-
-- adapter task sessions persist against `taskKey`
-- `taskKey` already falls back to `issueId`
-- OpenClaw already supports an issue-scoped session key
-
-This means "resume the CEO conversation later" works by reopening the same issue and waking the same agent on the same issue.
-
-### What not to add yet
-
-Do not add multi-thread-per-issue chat in the first pass.
-
-If Paperclip later needs several parallel threads on one issue, then add an explicit conversation identity and derive:
-
-- `taskKey = issue:<issueId>:conversation:<conversationId>`
-- OpenClaw `sessionKey = paperclip:conversation:<conversationId>`
-
-Until that requirement becomes real, one issue == one durable conversation is the simpler and better rule.
-
-## Billing Model
-
-Chat should not invent a separate billing pipeline.
-
-All chat cost should continue to roll up through the issue:
-
-- `cost_events.issueId`
-- project and goal rollups through existing relationships
-- issue `billingCode` when present
-
-If a conversation is important enough to exist, it is important enough to have a durable issue-backed audit and cost trail.
-
-This is another reason ephemeral freeform chat should not be the default.
-
-## UI Architecture
-
-### Recommended stack
-
-1. Keep Paperclip as the source of truth for message history and run state.
-2. Add `assistant-ui` as the rendering/composer layer.
-3. Build a Paperclip runtime adapter that maps:
-   - issue comments -> user/assistant messages
-   - live run deltas -> streaming assistant messages
-   - issue attachments -> chat attachments
-4. Keep current markdown rendering and code-block support where possible.
-
-### Interaction flow
-
-1. Board opens issue detail in "Chat" mode.
-2. Existing comment history is mapped into chat messages.
-3. When the board sends a message:
-   - `POST /api/issues/{id}/comments`
-   - optionally interrupt the active run if the UX wants "send and replace current response"
-4. Existing issue comment wakeup logic wakes the assignee.
-5. Existing `/issues/{id}/live-runs` and `/issues/{id}/active-run` data feeds drive streaming.
-6. When the run completes, durable state remains in comments/runs/activity as it does now.
-
-### Why this fits the current code
-
-Paperclip already has most of the backend pieces:
-
-- issue comments
-- run timeline
-- run log and event streaming
-- markdown rendering
-- attachment support
-- assignee wakeups on comments
-
-The missing piece is mostly the presentation and the mapping layer, not a new backend domain.
-
-## Agent Scope
-
-Do not launch this as "chat with every agent."
-
-Start narrower:
-
-- onboarding chat with CEO
-- workflow/review chat with CEO
-- maybe selected exec roles later
-
-Reasons:
-
-- it keeps the feature from becoming a second inbox/chat product
-- it limits permission and UX questions early
-- it matches the stated product demand
-
-If direct chat with other agents becomes useful later, the same issue-backed pattern can expand cleanly.
-
-## Recommended Delivery Phases
-
-### Phase 1: Chat UI on existing issues
-
-- add a chat presentation mode to issue detail
-- use `assistant-ui`
-- map comments + live runs into the chat surface
-- no schema change
-- no new API surface
-
-This is the highest-leverage step because it tests whether the UX is actually useful before product model expansion.
-
-### Phase 2: Conversation-flavored issues for CEO chat
-
-- add a lightweight conversation classification
-- support creation of CEO conversation issues from onboarding and workflow entry points
-- optionally hide these from normal backlog/board views by default
-
-The smallest implementation could be a label or issue metadata flag. If it becomes important enough, then promote it to a first-class issue subtype later.
-
-### Phase 3: Promotion and thread splitting only if needed
-
-Only if we later see a real need:
-
-- allow promoting a conversation to a formal task issue
-- allow several threads per issue with explicit conversation identity
-
-This should be demand-driven, not designed up front.
-
-## Clear Recommendation
-
-If the question is "what should we use?", the answer is:
-
-- use `assistant-ui` for the chat UI
-- do not treat raw Vercel AI SDK UI hooks as the main product answer
-- keep chat issue-backed in V1
-- use the current issue comment + run + session + billing model rather than inventing a parallel chat subsystem
-
-If the question is "how should we think about chat in Paperclip?", the answer is:
-
-- chat is a mode of interacting with issue-backed agent work
-- not a separate product silo
-- not an excuse to stop tracing work, cost, and session history back to the issue
-
-## Implementation Notes
-
-### Immediate implementation target
-
-The most defensible first build is:
-
-- add a chat tab or chat-focused layout on issue detail
-- back it with the currently assigned agent on that issue
-- use `assistant-ui` primitives over existing comments and live run events
-
-### Defer these until proven necessary
-
-- standalone global chat objects
-- multi-thread chat inside one issue
-- chat with every agent in the org
-- a second persistence layer for message history
-- separate cost tracking for chats
-
-## References
-
-- V1 communication model: `doc/SPEC-implementation.md`
-- Current issue/comment/run UI: `ui/src/pages/IssueDetail.tsx`, `ui/src/components/CommentThread.tsx`, `ui/src/components/LiveRunWidget.tsx`
-- Session persistence and task key derivation: `server/src/services/heartbeat.ts`, `packages/db/src/schema/agent_task_sessions.ts`
-- OpenClaw session routing: `packages/adapters/openclaw-gateway/README.md`
-- assistant-ui docs: <https://www.assistant-ui.com/docs>
-- assistant-ui repo: <https://github.com/assistant-ui/assistant-ui>
-- AI SDK transport docs: <https://ai-sdk.dev/docs/ai-sdk-ui/transport>

doc/spec/agent-runs.md

@@ -249,7 +249,7 @@ Runs local `claude` CLI directly.
   "cwd": "/absolute/or/relative/path",
   "promptTemplate": "You are agent {{agent.id}} ...",
   "model": "optional-model-id",
-  "maxTurnsPerRun": 300,
+  "maxTurnsPerRun": 80,
   "dangerouslySkipPermissions": true,
   "env": {"KEY": "VALUE"},
   "extraArgs": [],

doc/spec/ui.md

@@ -114,7 +114,7 @@ No section header — these are always at the top, below the company header.
   My Issues
 ```
 
-- **Inbox** — items requiring the board operator's attention. Badge count on the right. Includes: pending approvals, budget alerts, failed heartbeats. The number is the total unread/unresolved count.
+- **Inbox** — items requiring the board operator's attention. Badge count on the right. Includes: pending approvals, stale tasks, budget alerts, failed heartbeats. The number is the total unread/unresolved count.
 - **My Issues** — issues created by or assigned to the board operator.
 
 ### 3.3 Work Section

docs/adapters/claude-local.md

@@ -20,7 +20,7 @@ The `claude_local` adapter runs Anthropic's Claude Code CLI locally. It supports
 | `env` | object | No | Environment variables (supports secret refs) |
 | `timeoutSec` | number | No | Process timeout (0 = no timeout) |
 | `graceSec` | number | No | Grace period before force-kill |
-| `maxTurnsPerRun` | number | No | Max agentic turns per heartbeat (defaults to `300`) |
+| `maxTurnsPerRun` | number | No | Max agentic turns per heartbeat |
 | `dangerouslySkipPermissions` | boolean | No | Skip permission prompts (dev only) |
 
 ## Prompt Templates

docs/adapters/gemini-local.md

@@ -1,45 +0,0 @@
----
-title: Gemini Local
-summary: Gemini CLI local adapter setup and configuration
----
-
-The `gemini_local` adapter runs Google's Gemini CLI locally. It supports session persistence with `--resume`, skills injection, and structured `stream-json` output parsing.
-
-## Prerequisites
-
-- Gemini CLI installed (`gemini` command available)
-- `GEMINI_API_KEY` or `GOOGLE_API_KEY` set, or local Gemini CLI auth configured
-
-## Configuration Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `cwd` | string | Yes | Working directory for the agent process (absolute path; created automatically if missing when permissions allow) |
-| `model` | string | No | Gemini model to use. Defaults to `auto`. |
-| `promptTemplate` | string | No | Prompt used for all runs |
-| `instructionsFilePath` | string | No | Markdown instructions file prepended to the prompt |
-| `env` | object | No | Environment variables (supports secret refs) |
-| `timeoutSec` | number | No | Process timeout (0 = no timeout) |
-| `graceSec` | number | No | Grace period before force-kill |
-| `yolo` | boolean | No | Pass `--approval-mode yolo` for unattended operation |
-
-## Session Persistence
-
-The adapter persists Gemini session IDs between heartbeats. On the next wake, it resumes the existing conversation with `--resume` so the agent retains context.
-
-Session resume is cwd-aware: if the working directory changed since the last run, a fresh session starts instead.
-
-If resume fails with an unknown session error, the adapter automatically retries with a fresh session.
-
-## Skills Injection
-
-The adapter symlinks Paperclip skills into the Gemini global skills directory (`~/.gemini/skills`). Existing user skills are not overwritten.
-
-## Environment Test
-
-Use the "Test Environment" button in the UI to validate the adapter config. It checks:
-
-- Gemini CLI is installed and accessible
-- Working directory is absolute and available (auto-created if missing and permitted)
-- API key/auth hints (`GEMINI_API_KEY` or `GOOGLE_API_KEY`)
-- A live hello probe (`gemini --output-format json "Respond with hello."`) to verify CLI readiness

docs/adapters/overview.md

@@ -20,7 +20,6 @@ When a heartbeat fires, Paperclip:
 |---------|----------|-------------|
 | [Claude Local](/adapters/claude-local) | `claude_local` | Runs Claude Code CLI locally |
 | [Codex Local](/adapters/codex-local) | `codex_local` | Runs OpenAI Codex CLI locally |
-| [Gemini Local](/adapters/gemini-local) | `gemini_local` | Runs Gemini CLI locally |
 | OpenCode Local | `opencode_local` | Runs OpenCode CLI locally (multi-provider `provider/model`) |
 | OpenClaw | `openclaw` | Sends wake payloads to an OpenClaw webhook |
 | [Process](/adapters/process) | `process` | Executes arbitrary shell commands |
@@ -55,7 +54,7 @@ Three registries consume these modules:
 
 ## Choosing an Adapter
 
-- **Need a coding agent?** Use `claude_local`, `codex_local`, `gemini_local`, or `opencode_local`
+- **Need a coding agent?** Use `claude_local`, `codex_local`, or `opencode_local`
 - **Need to run a script or command?** Use `process`
 - **Need to call an external service?** Use `http`
 - **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter)

package.json

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

packages/adapter-utils/CHANGELOG.md

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

packages/adapter-utils/package.json

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

packages/adapter-utils/src/index.ts

@@ -22,9 +22,3 @@ export type {
   CLIAdapterModule,
   CreateConfigValues,
 } from "./types.js";
-export {
-  REDACTED_HOME_PATH_USER,
-  redactHomePathUserSegments,
-  redactHomePathUserSegmentsInValue,
-  redactTranscriptEntryPaths,
-} from "./log-redaction.js";

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

@@ -1,81 +0,0 @@
-import type { TranscriptEntry } from "./types.js";
-
-export const REDACTED_HOME_PATH_USER = "[]";
-
-const HOME_PATH_PATTERNS = [
-  {
-    regex: /\/Users\/[^/\\\s]+/g,
-    replace: `/Users/${REDACTED_HOME_PATH_USER}`,
-  },
-  {
-    regex: /\/home\/[^/\\\s]+/g,
-    replace: `/home/${REDACTED_HOME_PATH_USER}`,
-  },
-  {
-    regex: /([A-Za-z]:\\Users\\)[^\\/\s]+/g,
-    replace: `$1${REDACTED_HOME_PATH_USER}`,
-  },
-] as const;
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-}
-
-export function redactHomePathUserSegments(text: string): string {
-  let result = text;
-  for (const pattern of HOME_PATH_PATTERNS) {
-    result = result.replace(pattern.regex, pattern.replace);
-  }
-  return result;
-}
-
-export function redactHomePathUserSegmentsInValue<T>(value: T): T {
-  if (typeof value === "string") {
-    return redactHomePathUserSegments(value) as T;
-  }
-  if (Array.isArray(value)) {
-    return value.map((entry) => redactHomePathUserSegmentsInValue(entry)) as T;
-  }
-  if (!isPlainObject(value)) {
-    return value;
-  }
-
-  const redacted: Record<string, unknown> = {};
-  for (const [key, entry] of Object.entries(value)) {
-    redacted[key] = redactHomePathUserSegmentsInValue(entry);
-  }
-  return redacted as T;
-}
-
-export function redactTranscriptEntryPaths(entry: TranscriptEntry): TranscriptEntry {
-  switch (entry.kind) {
-    case "assistant":
-    case "thinking":
-    case "user":
-    case "stderr":
-    case "system":
-    case "stdout":
-      return { ...entry, text: redactHomePathUserSegments(entry.text) };
-    case "tool_call":
-      return { ...entry, name: redactHomePathUserSegments(entry.name), input: redactHomePathUserSegmentsInValue(entry.input) };
-    case "tool_result":
-      return { ...entry, content: redactHomePathUserSegments(entry.content) };
-    case "init":
-      return {
-        ...entry,
-        model: redactHomePathUserSegments(entry.model),
-        sessionId: redactHomePathUserSegments(entry.sessionId),
-      };
-    case "result":
-      return {
-        ...entry,
-        text: redactHomePathUserSegments(entry.text),
-        subtype: redactHomePathUserSegments(entry.subtype),
-        errors: entry.errors.map((error) => redactHomePathUserSegments(error)),
-      };
-    default:
-      return entry;
-  }
-}

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

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

packages/adapter-utils/src/types.ts

@@ -75,14 +75,6 @@ export interface AdapterExecutionResult {
   runtimeServices?: AdapterRuntimeServiceReport[];
   summary?: string | null;
   clearSession?: boolean;
-  question?: {
-    prompt: string;
-    choices: Array<{
-      key: string;
-      label: string;
-      description?: string;
-    }>;
-  } | null;
 }
 
 export interface AdapterSessionCodec {
@@ -197,7 +189,7 @@ export type TranscriptEntry =
   | { kind: "assistant"; ts: string; text: string; delta?: boolean }
   | { kind: "thinking"; ts: string; text: string; delta?: boolean }
   | { kind: "user"; ts: string; text: string }
-  | { kind: "tool_call"; ts: string; name: string; input: unknown; toolUseId?: string }
+  | { kind: "tool_call"; ts: string; name: string; input: unknown }
   | { kind: "tool_result"; ts: string; toolUseId: string; content: string; isError: boolean }
   | { kind: "init"; ts: string; model: string; sessionId: string }
   | { kind: "result"; ts: string; text: string; inputTokens: number; outputTokens: number; cachedTokens: number; costUsd: number; subtype: string; isError: boolean; errors: string[] }

packages/adapter-utils/tsconfig.json

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

packages/adapters/claude-local/CHANGELOG.md

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

packages/adapters/claude-local/package.json

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

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

@@ -71,12 +71,6 @@ export function parseClaudeStdoutLine(line: string, ts: string): TranscriptEntry
           kind: "tool_call",
           ts,
           name: typeof block.name === "string" ? block.name : "unknown",
-          toolUseId:
-            typeof block.id === "string"
-              ? block.id
-              : typeof block.tool_use_id === "string"
-                ? block.tool_use_id
-                : undefined,
           input: block.input ?? {},
         });
       }

packages/adapters/claude-local/tsconfig.json

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

packages/adapters/codex-local/CHANGELOG.md

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

packages/adapters/codex-local/package.json

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

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

@@ -1,8 +1,4 @@
-import {
-  redactHomePathUserSegments,
-  redactHomePathUserSegmentsInValue,
-  type TranscriptEntry,
-} from "@paperclipai/adapter-utils";
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
 
 function safeJsonParse(text: string): unknown {
   try {
@@ -43,12 +39,12 @@ function errorText(value: unknown): string {
 }
 
 function stringifyUnknown(value: unknown): string {
-  if (typeof value === "string") return redactHomePathUserSegments(value);
+  if (typeof value === "string") return value;
   if (value === null || value === undefined) return "";
   try {
-    return JSON.stringify(redactHomePathUserSegmentsInValue(value), null, 2);
+    return JSON.stringify(value, null, 2);
   } catch {
-    return redactHomePathUserSegments(String(value));
+    return String(value);
   }
 }
 
@@ -61,24 +57,22 @@ function parseCommandExecutionItem(
   const command = asString(item.command);
   const status = asString(item.status);
   const exitCode = typeof item.exit_code === "number" && Number.isFinite(item.exit_code) ? item.exit_code : null;
-  const safeCommand = redactHomePathUserSegments(command);
-  const output = redactHomePathUserSegments(asString(item.aggregated_output)).replace(/\s+$/, "");
+  const output = asString(item.aggregated_output).replace(/\s+$/, "");
 
   if (phase === "started") {
     return [{
       kind: "tool_call",
       ts,
       name: "command_execution",
-      toolUseId: id || command || "command_execution",
       input: {
         id,
-        command: safeCommand,
+        command,
       },
     }];
   }
 
   const lines: string[] = [];
-  if (safeCommand) lines.push(`command: ${safeCommand}`);
+  if (command) lines.push(`command: ${command}`);
   if (status) lines.push(`status: ${status}`);
   if (exitCode !== null) lines.push(`exit_code: ${exitCode}`);
   if (output) {
@@ -109,7 +103,7 @@ function parseFileChangeItem(item: Record<string, unknown>, ts: string): Transcr
     .filter((change): change is Record<string, unknown> => Boolean(change))
     .map((change) => {
       const kind = asString(change.kind, "update");
-      const path = redactHomePathUserSegments(asString(change.path, "unknown"));
+      const path = asString(change.path, "unknown");
       return `${kind} ${path}`;
     });
 
@@ -131,13 +125,13 @@ function parseCodexItem(
 
   if (itemType === "agent_message") {
     const text = asString(item.text);
-    if (text) return [{ kind: "assistant", ts, text: redactHomePathUserSegments(text) }];
+    if (text) return [{ kind: "assistant", ts, text }];
     return [];
   }
 
   if (itemType === "reasoning") {
     const text = asString(item.text);
-    if (text) return [{ kind: "thinking", ts, text: redactHomePathUserSegments(text) }];
+    if (text) return [{ kind: "thinking", ts, text }];
     return [{ kind: "system", ts, text: phase === "started" ? "reasoning started" : "reasoning completed" }];
   }
 
@@ -153,9 +147,8 @@ function parseCodexItem(
     return [{
       kind: "tool_call",
       ts,
-      name: redactHomePathUserSegments(asString(item.name, "unknown")),
-      toolUseId: asString(item.id),
-      input: redactHomePathUserSegmentsInValue(item.input ?? {}),
+      name: asString(item.name, "unknown"),
+      input: item.input ?? {},
     }];
   }
 
@@ -167,28 +160,24 @@ function parseCodexItem(
       asString(item.result) ||
       stringifyUnknown(item.content ?? item.output ?? item.result);
     const isError = item.is_error === true || asString(item.status) === "error";
-    return [{ kind: "tool_result", ts, toolUseId, content: redactHomePathUserSegments(content), isError }];
+    return [{ kind: "tool_result", ts, toolUseId, content, isError }];
   }
 
   if (itemType === "error" && phase === "completed") {
     const text = errorText(item.message ?? item.error ?? item);
-    return [{ kind: "stderr", ts, text: redactHomePathUserSegments(text || "error") }];
+    return [{ kind: "stderr", ts, text: text || "error" }];
   }
 
   const id = asString(item.id);
   const status = asString(item.status);
   const meta = [id ? `id=${id}` : "", status ? `status=${status}` : ""].filter(Boolean).join(" ");
-  return [{
-    kind: "system",
-    ts,
-    text: redactHomePathUserSegments(`item ${phase}: ${itemType || "unknown"}${meta ? ` (${meta})` : ""}`),
-  }];
+  return [{ kind: "system", ts, text: `item ${phase}: ${itemType || "unknown"}${meta ? ` (${meta})` : ""}` }];
 }
 
 export function parseCodexStdoutLine(line: string, ts: string): TranscriptEntry[] {
   const parsed = asRecord(safeJsonParse(line));
   if (!parsed) {
-    return [{ kind: "stdout", ts, text: redactHomePathUserSegments(line) }];
+    return [{ kind: "stdout", ts, text: line }];
   }
 
   const type = asString(parsed.type);
@@ -198,8 +187,8 @@ export function parseCodexStdoutLine(line: string, ts: string): TranscriptEntry[
     return [{
       kind: "init",
       ts,
-      model: redactHomePathUserSegments(asString(parsed.model, "codex")),
-      sessionId: redactHomePathUserSegments(threadId),
+      model: asString(parsed.model, "codex"),
+      sessionId: threadId,
     }];
   }
 
@@ -221,15 +210,15 @@ export function parseCodexStdoutLine(line: string, ts: string): TranscriptEntry[
     return [{
       kind: "result",
       ts,
-      text: redactHomePathUserSegments(asString(parsed.result)),
+      text: asString(parsed.result),
       inputTokens,
       outputTokens,
       cachedTokens,
       costUsd: asNumber(parsed.total_cost_usd),
-      subtype: redactHomePathUserSegments(asString(parsed.subtype)),
+      subtype: asString(parsed.subtype),
       isError: parsed.is_error === true,
       errors: Array.isArray(parsed.errors)
-        ? parsed.errors.map(errorText).map(redactHomePathUserSegments).filter(Boolean)
+        ? parsed.errors.map(errorText).filter(Boolean)
         : [],
     }];
   }
@@ -243,21 +232,21 @@ export function parseCodexStdoutLine(line: string, ts: string): TranscriptEntry[
     return [{
       kind: "result",
       ts,
-      text: redactHomePathUserSegments(asString(parsed.result)),
+      text: asString(parsed.result),
       inputTokens,
       outputTokens,
       cachedTokens,
       costUsd: asNumber(parsed.total_cost_usd),
-      subtype: redactHomePathUserSegments(asString(parsed.subtype, "turn.failed")),
+      subtype: asString(parsed.subtype, "turn.failed"),
       isError: true,
-      errors: message ? [redactHomePathUserSegments(message)] : [],
+      errors: message ? [message] : [],
     }];
   }
 
   if (type === "error") {
     const message = errorText(parsed.message ?? parsed.error ?? parsed);
-    return [{ kind: "stderr", ts, text: redactHomePathUserSegments(message || line) }];
+    return [{ kind: "stderr", ts, text: message || line }];
   }
 
-  return [{ kind: "stdout", ts, text: redactHomePathUserSegments(line) }];
+  return [{ kind: "stdout", ts, text: line }];
 }

packages/adapters/codex-local/tsconfig.json

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

packages/adapters/cursor-local/CHANGELOG.md

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

packages/adapters/cursor-local/package.json

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

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

@@ -142,12 +142,6 @@ function parseAssistantMessage(messageRaw: unknown, ts: string): TranscriptEntry
         kind: "tool_call",
         ts,
         name,
-        toolUseId:
-          asString(part.tool_use_id) ||
-          asString(part.toolUseId) ||
-          asString(part.call_id) ||
-          asString(part.id) ||
-          undefined,
         input,
       });
       continue;
@@ -205,7 +199,6 @@ function parseCursorToolCallEvent(event: Record<string, unknown>, ts: string): T
       kind: "tool_call",
       ts,
       name: toolName,
-      toolUseId: callId,
       input,
     }];
   }

packages/adapters/cursor-local/tsconfig.json

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

packages/adapters/gemini-local/package.json

@@ -1,51 +0,0 @@
-{
-  "name": "@paperclipai/adapter-gemini-local",
-  "version": "0.2.7",
-  "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",
-    "skills"
-  ],
-  "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/gemini-local/src/cli/format-event.ts

@@ -1,208 +0,0 @@
-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;
-}
-
-function asNumber(value: unknown, fallback = 0): number {
-  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
-}
-
-function stringifyUnknown(value: unknown): string {
-  if (typeof value === "string") return value;
-  if (value === null || value === undefined) return "";
-  try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    return String(value);
-  }
-}
-
-function errorText(value: unknown): string {
-  if (typeof value === "string") return value;
-  const rec = asRecord(value);
-  if (!rec) return "";
-  const msg =
-    (typeof rec.message === "string" && rec.message) ||
-    (typeof rec.error === "string" && rec.error) ||
-    (typeof rec.code === "string" && rec.code) ||
-    "";
-  if (msg) return msg;
-  try {
-    return JSON.stringify(rec);
-  } catch {
-    return "";
-  }
-}
-
-function printTextMessage(prefix: string, colorize: (text: string) => string, messageRaw: unknown): void {
-  if (typeof messageRaw === "string") {
-    const text = messageRaw.trim();
-    if (text) console.log(colorize(`${prefix}: ${text}`));
-    return;
-  }
-
-  const message = asRecord(messageRaw);
-  if (!message) return;
-
-  const directText = asString(message.text).trim();
-  if (directText) console.log(colorize(`${prefix}: ${directText}`));
-
-  const content = Array.isArray(message.content) ? message.content : [];
-  for (const partRaw of content) {
-    const part = asRecord(partRaw);
-    if (!part) continue;
-    const type = asString(part.type).trim();
-
-    if (type === "output_text" || type === "text" || type === "content") {
-      const text = asString(part.text).trim() || asString(part.content).trim();
-      if (text) console.log(colorize(`${prefix}: ${text}`));
-      continue;
-    }
-
-    if (type === "thinking") {
-      const text = asString(part.text).trim();
-      if (text) console.log(pc.gray(`thinking: ${text}`));
-      continue;
-    }
-
-    if (type === "tool_call") {
-      const name = asString(part.name, asString(part.tool, "tool"));
-      console.log(pc.yellow(`tool_call: ${name}`));
-      const input = part.input ?? part.arguments ?? part.args;
-      if (input !== undefined) console.log(pc.gray(stringifyUnknown(input)));
-      continue;
-    }
-
-    if (type === "tool_result" || type === "tool_response") {
-      const isError = part.is_error === true || asString(part.status).toLowerCase() === "error";
-      const contentText =
-        asString(part.output) ||
-        asString(part.text) ||
-        asString(part.result) ||
-        stringifyUnknown(part.output ?? part.result ?? part.text ?? part.response);
-      console.log((isError ? pc.red : pc.cyan)(`tool_result${isError ? " (error)" : ""}`));
-      if (contentText) console.log((isError ? pc.red : pc.gray)(contentText));
-    }
-  }
-}
-
-function printUsage(parsed: Record<string, unknown>) {
-  const usage = asRecord(parsed.usage) ?? asRecord(parsed.usageMetadata);
-  const usageMetadata = asRecord(usage?.usageMetadata);
-  const source = usageMetadata ?? usage ?? {};
-  const input = asNumber(source.input_tokens, asNumber(source.inputTokens, asNumber(source.promptTokenCount)));
-  const output = asNumber(source.output_tokens, asNumber(source.outputTokens, asNumber(source.candidatesTokenCount)));
-  const cached = asNumber(
-    source.cached_input_tokens,
-    asNumber(source.cachedInputTokens, asNumber(source.cachedContentTokenCount)),
-  );
-  const cost = asNumber(parsed.total_cost_usd, asNumber(parsed.cost_usd, asNumber(parsed.cost)));
-  console.log(pc.blue(`tokens: in=${input} out=${output} cached=${cached} cost=$${cost.toFixed(6)}`));
-}
-
-export function printGeminiStreamEvent(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);
-
-  if (type === "system") {
-    const subtype = asString(parsed.subtype);
-    if (subtype === "init") {
-      const sessionId =
-        asString(parsed.session_id) ||
-        asString(parsed.sessionId) ||
-        asString(parsed.sessionID) ||
-        asString(parsed.checkpoint_id);
-      const model = asString(parsed.model);
-      const details = [sessionId ? `session: ${sessionId}` : "", model ? `model: ${model}` : ""]
-        .filter(Boolean)
-        .join(", ");
-      console.log(pc.blue(`Gemini init${details ? ` (${details})` : ""}`));
-      return;
-    }
-    if (subtype === "error") {
-      const text = errorText(parsed.error ?? parsed.message ?? parsed.detail);
-      if (text) console.log(pc.red(`error: ${text}`));
-      return;
-    }
-    console.log(pc.blue(`system: ${subtype || "event"}`));
-    return;
-  }
-
-  if (type === "assistant") {
-    printTextMessage("assistant", pc.green, parsed.message);
-    return;
-  }
-
-  if (type === "user") {
-    printTextMessage("user", pc.gray, parsed.message);
-    return;
-  }
-
-  if (type === "thinking") {
-    const text = asString(parsed.text).trim() || asString(asRecord(parsed.delta)?.text).trim();
-    if (text) console.log(pc.gray(`thinking: ${text}`));
-    return;
-  }
-
-  if (type === "tool_call") {
-    const subtype = asString(parsed.subtype).trim().toLowerCase();
-    const toolCall = asRecord(parsed.tool_call ?? parsed.toolCall);
-    const [toolName] = toolCall ? Object.keys(toolCall) : [];
-    if (!toolCall || !toolName) {
-      console.log(pc.yellow(`tool_call${subtype ? `: ${subtype}` : ""}`));
-      return;
-    }
-    const payload = asRecord(toolCall[toolName]) ?? {};
-    if (subtype === "started" || subtype === "start") {
-      console.log(pc.yellow(`tool_call: ${toolName}`));
-      console.log(pc.gray(stringifyUnknown(payload.args ?? payload.input ?? payload.arguments ?? payload)));
-      return;
-    }
-    if (subtype === "completed" || subtype === "complete" || subtype === "finished") {
-      const isError =
-        parsed.is_error === true ||
-        payload.is_error === true ||
-        payload.error !== undefined ||
-        asString(payload.status).toLowerCase() === "error";
-      console.log((isError ? pc.red : pc.cyan)(`tool_result${isError ? " (error)" : ""}`));
-      console.log((isError ? pc.red : pc.gray)(stringifyUnknown(payload.result ?? payload.output ?? payload.error)));
-      return;
-    }
-    console.log(pc.yellow(`tool_call: ${toolName}${subtype ? ` (${subtype})` : ""}`));
-    return;
-  }
-
-  if (type === "result") {
-    printUsage(parsed);
-    const subtype = asString(parsed.subtype, "result");
-    const isError = parsed.is_error === true;
-    if (subtype || isError) {
-      console.log((isError ? pc.red : pc.blue)(`result: subtype=${subtype} is_error=${isError ? "true" : "false"}`));
-    }
-    return;
-  }
-
-  if (type === "error") {
-    const text = errorText(parsed.error ?? parsed.message ?? parsed.detail);
-    if (text) console.log(pc.red(`error: ${text}`));
-    return;
-  }
-
-  console.log(line);
-}

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

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

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

@@ -1,47 +0,0 @@
-export const type = "gemini_local";
-export const label = "Gemini CLI (local)";
-export const DEFAULT_GEMINI_LOCAL_MODEL = "auto";
-
-export const models = [
-  { id: DEFAULT_GEMINI_LOCAL_MODEL, label: "Auto" },
-  { id: "gemini-2.5-pro", label: "Gemini 2.5 Pro" },
-  { id: "gemini-2.5-flash", label: "Gemini 2.5 Flash" },
-  { id: "gemini-2.5-flash-lite", label: "Gemini 2.5 Flash Lite" },
-  { id: "gemini-2.0-flash", label: "Gemini 2.0 Flash" },
-  { id: "gemini-2.0-flash-lite", label: "Gemini 2.0 Flash Lite" },
-];
-
-export const agentConfigurationDoc = `# gemini_local agent configuration
-
-Adapter: gemini_local
-
-Use when:
-- You want Paperclip to run the Gemini CLI locally on the host machine
-- You want Gemini chat sessions resumed across heartbeats with --resume
-- You want Paperclip skills injected locally without polluting the global environment
-
-Don't use when:
-- You need webhook-style external invocation (use http or openclaw_gateway)
-- You only need a one-shot script without an AI coding agent loop (use process)
-- Gemini CLI is not installed 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 prepended to the run prompt
-- promptTemplate (string, optional): run prompt template
-- model (string, optional): Gemini model id. Defaults to auto.
-- sandbox (boolean, optional): run in sandbox mode (default: false, passes --sandbox=none)
-- command (string, optional): defaults to "gemini"
-- 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 positional prompt arguments, not stdin.
-- Sessions resume with --resume when stored session cwd matches the current cwd.
-- Paperclip auto-injects local skills into \`~/.gemini/skills/\` via symlinks, so the CLI can discover both credentials and skills in their natural location.
-- Authentication can use GEMINI_API_KEY / GOOGLE_API_KEY or local Gemini CLI login.
-`;

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

@@ -1,436 +0,0 @@
-import fs from "node:fs/promises";
-import type { Dirent } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";
-import {
-  asBoolean,
-  asNumber,
-  asString,
-  asStringArray,
-  buildPaperclipEnv,
-  ensureAbsoluteDirectory,
-  ensureCommandResolvable,
-  ensurePathInEnv,
-  parseObject,
-  redactEnvForLogs,
-  renderTemplate,
-  runChildProcess,
-} from "@paperclipai/adapter-utils/server-utils";
-import { DEFAULT_GEMINI_LOCAL_MODEL } from "../index.js";
-import {
-  describeGeminiFailure,
-  detectGeminiAuthRequired,
-  isGeminiTurnLimitResult,
-  isGeminiUnknownSessionError,
-  parseGeminiJsonl,
-} from "./parse.js";
-import { firstNonEmptyLine } from "./utils.js";
-
-const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),
-  path.resolve(__moduleDir, "../../../../../skills"),
-];
-
-function hasNonEmptyEnvValue(env: Record<string, string>, key: string): boolean {
-  const raw = env[key];
-  return typeof raw === "string" && raw.trim().length > 0;
-}
-
-function resolveGeminiBillingType(env: Record<string, string>): "api" | "subscription" {
-  return hasNonEmptyEnvValue(env, "GEMINI_API_KEY") || hasNonEmptyEnvValue(env, "GOOGLE_API_KEY")
-    ? "api"
-    : "subscription";
-}
-
-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 run_shell_command with curl to make Paperclip API requests.",
-    "GET example:",
-    `  run_shell_command({ command: "curl -s -H \\"Authorization: Bearer $PAPERCLIP_API_KEY\\" \\"$PAPERCLIP_API_URL/api/agents/me\\"" })`,
-    "POST/PATCH example:",
-    `  run_shell_command({ command: "curl -s -X POST -H \\"Authorization: Bearer $PAPERCLIP_API_KEY\\" -H 'Content-Type: application/json' -H \\"X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID\\" -d '{...}' \\"$PAPERCLIP_API_URL/api/issues/{id}/checkout\\"" })`,
-    "",
-    "",
-  ].join("\n");
-}
-
-async function resolvePaperclipSkillsDir(): Promise<string | null> {
-  for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
-    const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
-    if (isDir) return candidate;
-  }
-  return null;
-}
-
-function geminiSkillsHome(): string {
-  return path.join(os.homedir(), ".gemini", "skills");
-}
-
-/**
- * Inject Paperclip skills directly into `~/.gemini/skills/` via symlinks.
- * This avoids needing GEMINI_CLI_HOME overrides, so the CLI naturally finds
- * both its auth credentials and the injected skills in the real home directory.
- */
-async function ensureGeminiSkillsInjected(
-  onLog: AdapterExecutionContext["onLog"],
-): Promise<void> {
-  const skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return;
-
-  const skillsHome = geminiSkillsHome();
-  try {
-    await fs.mkdir(skillsHome, { recursive: true });
-  } catch (err) {
-    await onLog(
-      "stderr",
-      `[paperclip] Failed to prepare Gemini skills directory ${skillsHome}: ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    return;
-  }
-
-  let entries: Dirent[];
-  try {
-    entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  } catch (err) {
-    await onLog(
-      "stderr",
-      `[paperclip] Failed to read Paperclip skills from ${skillsDir}: ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    return;
-  }
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const source = path.join(skillsDir, entry.name);
-    const target = path.join(skillsHome, entry.name);
-    const existing = await fs.lstat(target).catch(() => null);
-    if (existing) continue;
-
-    try {
-      await fs.symlink(source, target);
-      await onLog("stderr", `[paperclip] Linked Gemini skill: ${entry.name}\n`);
-    } catch (err) {
-      await onLog(
-        "stderr",
-        `[paperclip] Failed to link Gemini skill "${entry.name}": ${err instanceof Error ? err.message : String(err)}\n`,
-      );
-    }
-  }
-}
-
-export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {
-  const { runId, agent, runtime, config, context, onLog, onMeta, authToken } = ctx;
-
-  const promptTemplate = asString(
-    config.promptTemplate,
-    "You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
-  );
-  const command = asString(config.command, "gemini");
-  const model = asString(config.model, DEFAULT_GEMINI_LOCAL_MODEL).trim();
-  const sandbox = asBoolean(config.sandbox, false);
-
-  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 workspaceHints = Array.isArray(context.paperclipWorkspaces)
-    ? context.paperclipWorkspaces.filter(
-      (value): 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();
-  await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
-  await ensureGeminiSkillsInjected(onLog);
-
-  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): value is string => typeof value === "string" && value.trim().length > 0)
-    : [];
-  if (wakeTaskId) env.PAPERCLIP_TASK_ID = wakeTaskId;
-  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 (effectiveWorkspaceCwd) env.PAPERCLIP_WORKSPACE_CWD = effectiveWorkspaceCwd;
-  if (workspaceSource) env.PAPERCLIP_WORKSPACE_SOURCE = workspaceSource;
-  if (workspaceId) env.PAPERCLIP_WORKSPACE_ID = workspaceId;
-  if (workspaceRepoUrl) env.PAPERCLIP_WORKSPACE_REPO_URL = workspaceRepoUrl;
-  if (workspaceRepoRef) env.PAPERCLIP_WORKSPACE_REPO_REF = workspaceRepoRef;
-  if (workspaceHints.length > 0) env.PAPERCLIP_WORKSPACES_JSON = JSON.stringify(workspaceHints);
-
-  for (const [key, value] of Object.entries(envConfig)) {
-    if (typeof value === "string") env[key] = value;
-  }
-  if (!hasExplicitApiKey && authToken) {
-    env.PAPERCLIP_API_KEY = authToken;
-  }
-  const billingType = resolveGeminiBillingType(env);
-  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
-  await ensureCommandResolvable(command, cwd, runtimeEnv);
-
-  const timeoutSec = asNumber(config.timeoutSec, 0);
-  const graceSec = asNumber(config.graceSec, 20);
-  const extraArgs = (() => {
-    const fromExtraArgs = asStringArray(config.extraArgs);
-    if (fromExtraArgs.length > 0) return fromExtraArgs;
-    return asStringArray(config.args);
-  })();
-
-  const runtimeSessionParams = parseObject(runtime.sessionParams);
-  const runtimeSessionId = asString(runtimeSessionParams.sessionId, runtime.sessionId ?? "");
-  const runtimeSessionCwd = asString(runtimeSessionParams.cwd, "");
-  const canResumeSession =
-    runtimeSessionId.length > 0 &&
-    (runtimeSessionCwd.length === 0 || path.resolve(runtimeSessionCwd) === path.resolve(cwd));
-  const sessionId = canResumeSession ? runtimeSessionId : null;
-  if (runtimeSessionId && !canResumeSession) {
-    await onLog(
-      "stderr",
-      `[paperclip] Gemini session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
-    );
-  }
-
-  const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
-  const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
-  let instructionsPrefix = "";
-  if (instructionsFilePath) {
-    try {
-      const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
-      instructionsPrefix =
-        `${instructionsContents}\n\n` +
-        `The above agent instructions were loaded from ${instructionsFilePath}. ` +
-        `Resolve any relative file references from ${instructionsDir}.\n\n`;
-      await onLog(
-        "stderr",
-        `[paperclip] Loaded agent instructions file: ${instructionsFilePath}\n`,
-      );
-    } catch (err) {
-      const reason = err instanceof Error ? err.message : String(err);
-      await onLog(
-        "stderr",
-        `[paperclip] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,
-      );
-    }
-  }
-  const commandNotes = (() => {
-    const notes: string[] = ["Prompt is passed to Gemini as the final positional argument."];
-    notes.push("Added --approval-mode yolo for unattended execution.");
-    if (!instructionsFilePath) return notes;
-    if (instructionsPrefix.length > 0) {
-      notes.push(
-        `Loaded agent instructions from ${instructionsFilePath}`,
-        `Prepended instructions + path directive to prompt (relative references from ${instructionsDir}).`,
-      );
-      return notes;
-    }
-    notes.push(
-      `Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
-    );
-    return notes;
-  })();
-
-  const renderedPrompt = renderTemplate(promptTemplate, {
-    agentId: agent.id,
-    companyId: agent.companyId,
-    runId,
-    company: { id: agent.companyId },
-    agent,
-    run: { id: runId, source: "on_demand" },
-    context,
-  });
-  const paperclipEnvNote = renderPaperclipEnvNote(env);
-  const apiAccessNote = renderApiAccessNote(env);
-  const prompt = `${instructionsPrefix}${paperclipEnvNote}${apiAccessNote}${renderedPrompt}`;
-
-  const buildArgs = (resumeSessionId: string | null) => {
-    const args = ["--output-format", "stream-json"];
-    if (resumeSessionId) args.push("--resume", resumeSessionId);
-    if (model && model !== DEFAULT_GEMINI_LOCAL_MODEL) args.push("--model", model);
-    args.push("--approval-mode", "yolo");
-    if (sandbox) {
-      args.push("--sandbox");
-    } else {
-      args.push("--sandbox=none");
-    }
-    if (extraArgs.length > 0) args.push(...extraArgs);
-    args.push(prompt);
-    return args;
-  };
-
-  const runAttempt = async (resumeSessionId: string | null) => {
-    const args = buildArgs(resumeSessionId);
-    if (onMeta) {
-      await onMeta({
-        adapterType: "gemini_local",
-        command,
-        cwd,
-        commandNotes,
-        commandArgs: args.map((value, index) => (
-          index === args.length - 1 ? `<prompt ${prompt.length} chars>` : value
-        )),
-        env: redactEnvForLogs(env),
-        prompt,
-        context,
-      });
-    }
-
-    const proc = await runChildProcess(runId, command, args, {
-      cwd,
-      env,
-      timeoutSec,
-      graceSec,
-      onLog,
-    });
-    return {
-      proc,
-      parsed: parseGeminiJsonl(proc.stdout),
-    };
-  };
-
-  const toResult = (
-    attempt: {
-      proc: {
-        exitCode: number | null;
-        signal: string | null;
-        timedOut: boolean;
-        stdout: string;
-        stderr: string;
-      };
-      parsed: ReturnType<typeof parseGeminiJsonl>;
-    },
-    clearSessionOnMissingSession = false,
-    isRetry = false,
-  ): AdapterExecutionResult => {
-    const authMeta = detectGeminiAuthRequired({
-      parsed: attempt.parsed.resultEvent,
-      stdout: attempt.proc.stdout,
-      stderr: attempt.proc.stderr,
-    });
-
-    if (attempt.proc.timedOut) {
-      return {
-        exitCode: attempt.proc.exitCode,
-        signal: attempt.proc.signal,
-        timedOut: true,
-        errorMessage: `Timed out after ${timeoutSec}s`,
-        errorCode: authMeta.requiresAuth ? "gemini_auth_required" : null,
-        clearSession: clearSessionOnMissingSession,
-      };
-    }
-
-    const clearSessionForTurnLimit = isGeminiTurnLimitResult(attempt.parsed.resultEvent, attempt.proc.exitCode);
-
-    // On retry, don't fall back to old session ID — the old session was stale
-    const canFallbackToRuntimeSession = !isRetry;
-    const resolvedSessionId = attempt.parsed.sessionId
-      ?? (canFallbackToRuntimeSession ? (runtimeSessionId ?? runtime.sessionId ?? null) : null);
-    const resolvedSessionParams = resolvedSessionId
-      ? ({
-        sessionId: resolvedSessionId,
-        cwd,
-        ...(workspaceId ? { workspaceId } : {}),
-        ...(workspaceRepoUrl ? { repoUrl: workspaceRepoUrl } : {}),
-        ...(workspaceRepoRef ? { repoRef: workspaceRepoRef } : {}),
-      } as Record<string, unknown>)
-      : null;
-    const parsedError = typeof attempt.parsed.errorMessage === "string" ? attempt.parsed.errorMessage.trim() : "";
-    const stderrLine = firstNonEmptyLine(attempt.proc.stderr);
-    const structuredFailure = attempt.parsed.resultEvent
-      ? describeGeminiFailure(attempt.parsed.resultEvent)
-      : null;
-    const fallbackErrorMessage =
-      parsedError ||
-      structuredFailure ||
-      stderrLine ||
-      `Gemini exited with code ${attempt.proc.exitCode ?? -1}`;
-
-    return {
-      exitCode: attempt.proc.exitCode,
-      signal: attempt.proc.signal,
-      timedOut: false,
-      errorMessage: (attempt.proc.exitCode ?? 0) === 0 ? null : fallbackErrorMessage,
-      errorCode: (attempt.proc.exitCode ?? 0) !== 0 && authMeta.requiresAuth ? "gemini_auth_required" : null,
-      usage: attempt.parsed.usage,
-      sessionId: resolvedSessionId,
-      sessionParams: resolvedSessionParams,
-      sessionDisplayId: resolvedSessionId,
-      provider: "google",
-      model,
-      billingType,
-      costUsd: attempt.parsed.costUsd,
-      resultJson: attempt.parsed.resultEvent ?? {
-        stdout: attempt.proc.stdout,
-        stderr: attempt.proc.stderr,
-      },
-      summary: attempt.parsed.summary,
-      question: attempt.parsed.question,
-      clearSession: clearSessionForTurnLimit || Boolean(clearSessionOnMissingSession && !resolvedSessionId),
-    };
-  };
-
-  const initial = await runAttempt(sessionId);
-  if (
-    sessionId &&
-    !initial.proc.timedOut &&
-    (initial.proc.exitCode ?? 0) !== 0 &&
-    isGeminiUnknownSessionError(initial.proc.stdout, initial.proc.stderr)
-  ) {
-    await onLog(
-      "stderr",
-      `[paperclip] Gemini resume session "${sessionId}" is unavailable; retrying with a fresh session.\n`,
-    );
-    const retry = await runAttempt(null);
-    return toResult(retry, true, true);
-  }
-
-  return toResult(initial);
-}

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

@@ -1,70 +0,0 @@
-export { execute } from "./execute.js";
-export { testEnvironment } from "./test.js";
-export {
-  parseGeminiJsonl,
-  isGeminiUnknownSessionError,
-  describeGeminiFailure,
-  detectGeminiAuthRequired,
-  isGeminiTurnLimitResult,
-} from "./parse.js";
-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)
-    );
-  },
-};

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

@@ -1,263 +0,0 @@
-import { asNumber, asString, parseJson, parseObject } from "@paperclipai/adapter-utils/server-utils";
-
-function collectMessageText(message: unknown): string[] {
-  if (typeof message === "string") {
-    const trimmed = message.trim();
-    return trimmed ? [trimmed] : [];
-  }
-
-  const record = parseObject(message);
-  const direct = asString(record.text, "").trim();
-  const lines: string[] = direct ? [direct] : [];
-  const content = Array.isArray(record.content) ? record.content : [];
-
-  for (const partRaw of content) {
-    const part = parseObject(partRaw);
-    const type = asString(part.type, "").trim();
-    if (type === "output_text" || type === "text" || type === "content") {
-      const text = asString(part.text, "").trim() || asString(part.content, "").trim();
-      if (text) lines.push(text);
-    }
-  }
-
-  return lines;
-}
-
-function readSessionId(event: Record<string, unknown>): string | null {
-  return (
-    asString(event.session_id, "").trim() ||
-    asString(event.sessionId, "").trim() ||
-    asString(event.sessionID, "").trim() ||
-    asString(event.checkpoint_id, "").trim() ||
-    asString(event.thread_id, "").trim() ||
-    null
-  );
-}
-
-function asErrorText(value: unknown): string {
-  if (typeof value === "string") return value;
-  const rec = parseObject(value);
-  const message =
-    asString(rec.message, "") ||
-    asString(rec.error, "") ||
-    asString(rec.code, "") ||
-    asString(rec.detail, "");
-  if (message) return message;
-  try {
-    return JSON.stringify(rec);
-  } catch {
-    return "";
-  }
-}
-
-function accumulateUsage(
-  target: { inputTokens: number; cachedInputTokens: number; outputTokens: number },
-  usageRaw: unknown,
-) {
-  const usage = parseObject(usageRaw);
-  const usageMetadata = parseObject(usage.usageMetadata);
-  const source = Object.keys(usageMetadata).length > 0 ? usageMetadata : usage;
-
-  target.inputTokens += asNumber(
-    source.input_tokens,
-    asNumber(source.inputTokens, asNumber(source.promptTokenCount, 0)),
-  );
-  target.cachedInputTokens += asNumber(
-    source.cached_input_tokens,
-    asNumber(source.cachedInputTokens, asNumber(source.cachedContentTokenCount, 0)),
-  );
-  target.outputTokens += asNumber(
-    source.output_tokens,
-    asNumber(source.outputTokens, asNumber(source.candidatesTokenCount, 0)),
-  );
-}
-
-export function parseGeminiJsonl(stdout: string) {
-  let sessionId: string | null = null;
-  const messages: string[] = [];
-  let errorMessage: string | null = null;
-  let costUsd: number | null = null;
-  let resultEvent: Record<string, unknown> | null = null;
-  let question: { prompt: string; choices: Array<{ key: string; label: string; description?: string }> } | null = null;
-  const usage = {
-    inputTokens: 0,
-    cachedInputTokens: 0,
-    outputTokens: 0,
-  };
-
-  for (const rawLine of stdout.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line) continue;
-
-    const event = parseJson(line);
-    if (!event) continue;
-
-    const foundSessionId = readSessionId(event);
-    if (foundSessionId) sessionId = foundSessionId;
-
-    const type = asString(event.type, "").trim();
-
-    if (type === "assistant") {
-      messages.push(...collectMessageText(event.message));
-      const messageObj = parseObject(event.message);
-      const content = Array.isArray(messageObj.content) ? messageObj.content : [];
-      for (const partRaw of content) {
-        const part = parseObject(partRaw);
-        if (asString(part.type, "").trim() === "question") {
-          question = {
-            prompt: asString(part.prompt, "").trim(),
-            choices: (Array.isArray(part.choices) ? part.choices : []).map((choiceRaw) => {
-              const choice = parseObject(choiceRaw);
-              return {
-                key: asString(choice.key, "").trim(),
-                label: asString(choice.label, "").trim(),
-                description: asString(choice.description, "").trim() || undefined,
-              };
-            }),
-          };
-          break; // only one question per message
-        }
-      }
-      continue;
-    }
-
-    if (type === "result") {
-      resultEvent = event;
-      accumulateUsage(usage, event.usage ?? event.usageMetadata);
-      const resultText =
-        asString(event.result, "").trim() ||
-        asString(event.text, "").trim() ||
-        asString(event.response, "").trim();
-      if (resultText && messages.length === 0) messages.push(resultText);
-      costUsd = asNumber(event.total_cost_usd, asNumber(event.cost_usd, asNumber(event.cost, costUsd ?? 0))) || costUsd;
-      const isError = event.is_error === true || asString(event.subtype, "").toLowerCase() === "error";
-      if (isError) {
-        const text = asErrorText(event.error ?? event.message ?? event.result).trim();
-        if (text) errorMessage = text;
-      }
-      continue;
-    }
-
-    if (type === "error") {
-      const text = asErrorText(event.error ?? event.message ?? event.detail).trim();
-      if (text) errorMessage = text;
-      continue;
-    }
-
-    if (type === "system") {
-      const subtype = asString(event.subtype, "").trim().toLowerCase();
-      if (subtype === "error") {
-        const text = asErrorText(event.error ?? event.message ?? event.detail).trim();
-        if (text) errorMessage = text;
-      }
-      continue;
-    }
-
-    if (type === "text") {
-      const part = parseObject(event.part);
-      const text = asString(part.text, "").trim();
-      if (text) messages.push(text);
-      continue;
-    }
-
-    if (type === "step_finish" || event.usage || event.usageMetadata) {
-      accumulateUsage(usage, event.usage ?? event.usageMetadata);
-      costUsd = asNumber(event.total_cost_usd, asNumber(event.cost_usd, asNumber(event.cost, costUsd ?? 0))) || costUsd;
-      continue;
-    }
-  }
-
-  return {
-    sessionId,
-    summary: messages.join("\n\n").trim(),
-    usage,
-    costUsd,
-    errorMessage,
-    resultEvent,
-    question,
-  };
-}
-
-export function isGeminiUnknownSessionError(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|checkpoint\s+.*\s+not\s+found|cannot\s+resume|failed\s+to\s+resume/i.test(
-    haystack,
-  );
-}
-
-function extractGeminiErrorMessages(parsed: Record<string, unknown>): string[] {
-  const messages: string[] = [];
-  const errorMsg = asString(parsed.error, "").trim();
-  if (errorMsg) messages.push(errorMsg);
-
-  const raw = Array.isArray(parsed.errors) ? parsed.errors : [];
-  for (const entry of raw) {
-    if (typeof entry === "string") {
-      const msg = entry.trim();
-      if (msg) messages.push(msg);
-      continue;
-    }
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) continue;
-    const obj = entry as Record<string, unknown>;
-    const msg = asString(obj.message, "") || asString(obj.error, "") || asString(obj.code, "");
-    if (msg) {
-      messages.push(msg);
-      continue;
-    }
-    try {
-      messages.push(JSON.stringify(obj));
-    } catch {
-      // skip non-serializable entry
-    }
-  }
-
-  return messages;
-}
-
-export function describeGeminiFailure(parsed: Record<string, unknown>): string | null {
-  const status = asString(parsed.status, "");
-  const errors = extractGeminiErrorMessages(parsed);
-
-  const detail = errors[0] ?? "";
-  const parts = ["Gemini run failed"];
-  if (status) parts.push(`status=${status}`);
-  if (detail) parts.push(detail);
-  return parts.length > 1 ? parts.join(": ") : null;
-}
-
-const GEMINI_AUTH_REQUIRED_RE = /(?:not\s+authenticated|please\s+authenticate|api[_ ]?key\s+(?:required|missing|invalid)|authentication\s+required|unauthorized|invalid\s+credentials|not\s+logged\s+in|login\s+required|run\s+`?gemini\s+auth(?:\s+login)?`?\s+first)/i;
-
-export function detectGeminiAuthRequired(input: {
-  parsed: Record<string, unknown> | null;
-  stdout: string;
-  stderr: string;
-}): { requiresAuth: boolean } {
-  const errors = extractGeminiErrorMessages(input.parsed ?? {});
-  const messages = [...errors, input.stdout, input.stderr]
-    .join("\n")
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean);
-
-  const requiresAuth = messages.some((line) => GEMINI_AUTH_REQUIRED_RE.test(line));
-  return { requiresAuth };
-}
-
-export function isGeminiTurnLimitResult(
-  parsed: Record<string, unknown> | null | undefined,
-  exitCode?: number | null,
-): boolean {
-  if (exitCode === 53) return true;
-  if (!parsed) return false;
-
-  const status = asString(parsed.status, "").trim().toLowerCase();
-  if (status === "turn_limit" || status === "max_turns") return true;
-
-  const error = asString(parsed.error, "").trim();
-  return /turn\s*limit|max(?:imum)?\s+turns?/i.test(error);
-}

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

@@ -1,223 +0,0 @@
-import path from "node:path";
-import type {
-  AdapterEnvironmentCheck,
-  AdapterEnvironmentTestContext,
-  AdapterEnvironmentTestResult,
-} from "@paperclipai/adapter-utils";
-import {
-  asBoolean,
-  asString,
-  asStringArray,
-  ensureAbsoluteDirectory,
-  ensureCommandResolvable,
-  ensurePathInEnv,
-  parseObject,
-  runChildProcess,
-} from "@paperclipai/adapter-utils/server-utils";
-import { DEFAULT_GEMINI_LOCAL_MODEL } from "../index.js";
-import { detectGeminiAuthRequired, parseGeminiJsonl } from "./parse.js";
-import { firstNonEmptyLine } from "./utils.js";
-
-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 isNonEmpty(value: unknown): value is string {
-  return typeof value === "string" && value.trim().length > 0;
-}
-
-function commandLooksLike(command: string, expected: string): boolean {
-  const base = path.basename(command).toLowerCase();
-  return base === expected || base === `${expected}.cmd` || base === `${expected}.exe`;
-}
-
-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 - 1)}…` : clean;
-}
-
-export async function testEnvironment(
-  ctx: AdapterEnvironmentTestContext,
-): Promise<AdapterEnvironmentTestResult> {
-  const checks: AdapterEnvironmentCheck[] = [];
-  const config = parseObject(ctx.config);
-  const command = asString(config.command, "gemini");
-  const cwd = asString(config.cwd, process.cwd());
-
-  try {
-    await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
-    checks.push({
-      code: "gemini_cwd_valid",
-      level: "info",
-      message: `Working directory is valid: ${cwd}`,
-    });
-  } catch (err) {
-    checks.push({
-      code: "gemini_cwd_invalid",
-      level: "error",
-      message: err instanceof Error ? err.message : "Invalid working directory",
-      detail: cwd,
-    });
-  }
-
-  const envConfig = parseObject(config.env);
-  const env: Record<string, string> = {};
-  for (const [key, value] of Object.entries(envConfig)) {
-    if (typeof value === "string") env[key] = value;
-  }
-  const runtimeEnv = ensurePathInEnv({ ...process.env, ...env });
-  try {
-    await ensureCommandResolvable(command, cwd, runtimeEnv);
-    checks.push({
-      code: "gemini_command_resolvable",
-      level: "info",
-      message: `Command is executable: ${command}`,
-    });
-  } catch (err) {
-    checks.push({
-      code: "gemini_command_unresolvable",
-      level: "error",
-      message: err instanceof Error ? err.message : "Command is not executable",
-      detail: command,
-    });
-  }
-
-  const configGeminiApiKey = env.GEMINI_API_KEY;
-  const hostGeminiApiKey = process.env.GEMINI_API_KEY;
-  const configGoogleApiKey = env.GOOGLE_API_KEY;
-  const hostGoogleApiKey = process.env.GOOGLE_API_KEY;
-  const hasGca = env.GOOGLE_GENAI_USE_GCA === "true" || process.env.GOOGLE_GENAI_USE_GCA === "true";
-  if (
-    isNonEmpty(configGeminiApiKey) ||
-    isNonEmpty(hostGeminiApiKey) ||
-    isNonEmpty(configGoogleApiKey) ||
-    isNonEmpty(hostGoogleApiKey) ||
-    hasGca
-  ) {
-    const source = hasGca
-      ? "Google account login (GCA)"
-      : isNonEmpty(configGeminiApiKey) || isNonEmpty(configGoogleApiKey)
-        ? "adapter config env"
-        : "server environment";
-    checks.push({
-      code: "gemini_api_key_present",
-      level: "info",
-      message: "Gemini API credentials are set for CLI authentication.",
-      detail: `Detected in ${source}.`,
-    });
-  } else {
-    checks.push({
-      code: "gemini_api_key_missing",
-      level: "info",
-      message: "No explicit API key detected. Gemini CLI may still authenticate via `gemini auth login` (OAuth).",
-      hint: "If the hello probe fails with an auth error, set GEMINI_API_KEY or GOOGLE_API_KEY in adapter env, or run `gemini auth login`.",
-    });
-  }
-
-  const canRunProbe =
-    checks.every((check) => check.code !== "gemini_cwd_invalid" && check.code !== "gemini_command_unresolvable");
-  if (canRunProbe) {
-    if (!commandLooksLike(command, "gemini")) {
-      checks.push({
-        code: "gemini_hello_probe_skipped_custom_command",
-        level: "info",
-        message: "Skipped hello probe because command is not `gemini`.",
-        detail: command,
-        hint: "Use the `gemini` CLI command to run the automatic installation and auth probe.",
-      });
-    } else {
-      const model = asString(config.model, DEFAULT_GEMINI_LOCAL_MODEL).trim();
-      const approvalMode = asString(config.approvalMode, asBoolean(config.yolo, false) ? "yolo" : "default");
-      const sandbox = asBoolean(config.sandbox, false);
-      const extraArgs = (() => {
-        const fromExtraArgs = asStringArray(config.extraArgs);
-        if (fromExtraArgs.length > 0) return fromExtraArgs;
-        return asStringArray(config.args);
-      })();
-
-      const args = ["--output-format", "stream-json"];
-      if (model && model !== DEFAULT_GEMINI_LOCAL_MODEL) args.push("--model", model);
-      if (approvalMode !== "default") args.push("--approval-mode", approvalMode);
-      if (sandbox) {
-        args.push("--sandbox");
-      } else {
-        args.push("--sandbox=none");
-      }
-      if (extraArgs.length > 0) args.push(...extraArgs);
-      args.push("Respond with hello.");
-
-      const probe = await runChildProcess(
-        `gemini-envtest-${Date.now()}-${Math.random().toString(16).slice(2)}`,
-        command,
-        args,
-        {
-          cwd,
-          env,
-          timeoutSec: 45,
-          graceSec: 5,
-          onLog: async () => { },
-        },
-      );
-      const parsed = parseGeminiJsonl(probe.stdout);
-      const detail = summarizeProbeDetail(probe.stdout, probe.stderr, parsed.errorMessage);
-      const authMeta = detectGeminiAuthRequired({
-        parsed: parsed.resultEvent,
-        stdout: probe.stdout,
-        stderr: probe.stderr,
-      });
-
-      if (probe.timedOut) {
-        checks.push({
-          code: "gemini_hello_probe_timed_out",
-          level: "warn",
-          message: "Gemini hello probe timed out.",
-          hint: "Retry the probe. If this persists, verify Gemini can run `Respond with hello.` from this directory manually.",
-        });
-      } else if ((probe.exitCode ?? 1) === 0) {
-        const summary = parsed.summary.trim();
-        const hasHello = /\bhello\b/i.test(summary);
-        checks.push({
-          code: hasHello ? "gemini_hello_probe_passed" : "gemini_hello_probe_unexpected_output",
-          level: hasHello ? "info" : "warn",
-          message: hasHello
-            ? "Gemini hello probe succeeded."
-            : "Gemini probe ran but did not return `hello` as expected.",
-          ...(summary ? { detail: summary.replace(/\s+/g, " ").trim().slice(0, 240) } : {}),
-          ...(hasHello
-            ? {}
-            : {
-              hint: "Try `gemini --output-format json \"Respond with hello.\"` manually to inspect full output.",
-            }),
-        });
-      } else if (authMeta.requiresAuth) {
-        checks.push({
-          code: "gemini_hello_probe_auth_required",
-          level: "warn",
-          message: "Gemini CLI is installed, but authentication is not ready.",
-          ...(detail ? { detail } : {}),
-          hint: "Run `gemini auth` or configure GEMINI_API_KEY / GOOGLE_API_KEY in adapter env/shell, then retry the probe.",
-        });
-      } else {
-        checks.push({
-          code: "gemini_hello_probe_failed",
-          level: "error",
-          message: "Gemini hello probe failed.",
-          ...(detail ? { detail } : {}),
-          hint: "Run `gemini --output-format json \"Respond with hello.\"` manually in this working directory to debug.",
-        });
-      }
-    }
-  }
-
-  return {
-    adapterType: ctx.adapterType,
-    status: summarizeStatus(checks),
-    checks,
-    testedAt: new Date().toISOString(),
-  };
-}

packages/adapters/gemini-local/src/server/utils.ts

@@ -1,8 +0,0 @@
-export function firstNonEmptyLine(text: string): string {
-    return (
-        text
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .find(Boolean) ?? ""
-    );
-}

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

@@ -1,75 +0,0 @@
-import type { CreateConfigValues } from "@paperclipai/adapter-utils";
-import { DEFAULT_GEMINI_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 buildGeminiLocalConfig(v: CreateConfigValues): Record<string, unknown> {
-  const ac: Record<string, unknown> = {};
-  if (v.cwd) ac.cwd = v.cwd;
-  if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
-  if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
-  ac.model = v.model || DEFAULT_GEMINI_LOCAL_MODEL;
-  ac.timeoutSec = 0;
-  ac.graceSec = 15;
-  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;
-  ac.sandbox = !v.dangerouslyBypassSandbox;
-
-  if (v.command) ac.command = v.command;
-  if (v.extraArgs) ac.extraArgs = parseCommaArgs(v.extraArgs);
-  return ac;
-}

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

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

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

@@ -1,274 +0,0 @@
-import type { TranscriptEntry } from "@paperclipai/adapter-utils";
-
-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 asNumber(value: unknown, fallback = 0): number {
-  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
-}
-
-function stringifyUnknown(value: unknown): string {
-  if (typeof value === "string") return value;
-  if (value === null || value === undefined) return "";
-  try {
-    return JSON.stringify(value, null, 2);
-  } catch {
-    return String(value);
-  }
-}
-
-function errorText(value: unknown): string {
-  if (typeof value === "string") return value;
-  const rec = asRecord(value);
-  if (!rec) return "";
-  const msg =
-    (typeof rec.message === "string" && rec.message) ||
-    (typeof rec.error === "string" && rec.error) ||
-    (typeof rec.code === "string" && rec.code) ||
-    "";
-  if (msg) return msg;
-  try {
-    return JSON.stringify(rec);
-  } catch {
-    return "";
-  }
-}
-
-function collectTextEntries(messageRaw: unknown, ts: string, kind: "assistant" | "user"): TranscriptEntry[] {
-  if (typeof messageRaw === "string") {
-    const text = messageRaw.trim();
-    return text ? [{ kind, ts, text }] : [];
-  }
-
-  const message = asRecord(messageRaw);
-  if (!message) return [];
-
-  const entries: TranscriptEntry[] = [];
-  const directText = asString(message.text).trim();
-  if (directText) entries.push({ kind, ts, text: directText });
-
-  const content = Array.isArray(message.content) ? message.content : [];
-  for (const partRaw of content) {
-    const part = asRecord(partRaw);
-    if (!part) continue;
-    const type = asString(part.type).trim();
-    if (type !== "output_text" && type !== "text" && type !== "content") continue;
-    const text = asString(part.text).trim() || asString(part.content).trim();
-    if (text) entries.push({ kind, ts, text });
-  }
-
-  return entries;
-}
-
-function parseAssistantMessage(messageRaw: unknown, ts: string): TranscriptEntry[] {
-  if (typeof messageRaw === "string") {
-    const text = messageRaw.trim();
-    return text ? [{ kind: "assistant", ts, text }] : [];
-  }
-
-  const message = asRecord(messageRaw);
-  if (!message) return [];
-
-  const entries: TranscriptEntry[] = [];
-  const directText = asString(message.text).trim();
-  if (directText) entries.push({ kind: "assistant", ts, text: directText });
-
-  const content = Array.isArray(message.content) ? message.content : [];
-  for (const partRaw of content) {
-    const part = asRecord(partRaw);
-    if (!part) continue;
-    const type = asString(part.type).trim();
-
-    if (type === "output_text" || type === "text" || type === "content") {
-      const text = asString(part.text).trim() || asString(part.content).trim();
-      if (text) entries.push({ kind: "assistant", ts, text });
-      continue;
-    }
-
-    if (type === "thinking") {
-      const text = asString(part.text).trim();
-      if (text) entries.push({ kind: "thinking", ts, text });
-      continue;
-    }
-
-    if (type === "tool_call") {
-      const name = asString(part.name, asString(part.tool, "tool"));
-      entries.push({
-        kind: "tool_call",
-        ts,
-        name,
-        input: part.input ?? part.arguments ?? part.args ?? {},
-      });
-      continue;
-    }
-
-    if (type === "tool_result" || type === "tool_response") {
-      const toolUseId =
-        asString(part.tool_use_id) ||
-        asString(part.toolUseId) ||
-        asString(part.call_id) ||
-        asString(part.id) ||
-        "tool_result";
-      const contentText =
-        asString(part.output) ||
-        asString(part.text) ||
-        asString(part.result) ||
-        stringifyUnknown(part.output ?? part.result ?? part.text ?? part.response);
-      const isError = part.is_error === true || asString(part.status).toLowerCase() === "error";
-      entries.push({
-        kind: "tool_result",
-        ts,
-        toolUseId,
-        content: contentText,
-        isError,
-      });
-    }
-  }
-
-  return entries;
-}
-
-function parseTopLevelToolEvent(parsed: Record<string, unknown>, ts: string): TranscriptEntry[] {
-  const subtype = asString(parsed.subtype).trim().toLowerCase();
-  const callId = asString(parsed.call_id, asString(parsed.callId, asString(parsed.id, "tool_call")));
-  const toolCall = asRecord(parsed.tool_call ?? parsed.toolCall);
-  if (!toolCall) {
-    return [{ kind: "system", ts, text: `tool_call${subtype ? ` (${subtype})` : ""}` }];
-  }
-
-  const [toolName] = Object.keys(toolCall);
-  if (!toolName) {
-    return [{ kind: "system", ts, text: `tool_call${subtype ? ` (${subtype})` : ""}` }];
-  }
-  const payload = asRecord(toolCall[toolName]) ?? {};
-
-  if (subtype === "started" || subtype === "start") {
-    return [{
-      kind: "tool_call",
-      ts,
-      name: toolName,
-      input: payload.args ?? payload.input ?? payload.arguments ?? payload,
-    }];
-  }
-
-  if (subtype === "completed" || subtype === "complete" || subtype === "finished") {
-    const result = payload.result ?? payload.output ?? payload.error;
-    const isError =
-      parsed.is_error === true ||
-      payload.is_error === true ||
-      payload.error !== undefined ||
-      asString(payload.status).toLowerCase() === "error";
-    return [{
-      kind: "tool_result",
-      ts,
-      toolUseId: callId,
-      content: result !== undefined ? stringifyUnknown(result) : `${toolName} completed`,
-      isError,
-    }];
-  }
-
-  return [{ kind: "system", ts, text: `tool_call${subtype ? ` (${subtype})` : ""}: ${toolName}` }];
-}
-
-function readSessionId(parsed: Record<string, unknown>): string {
-  return (
-    asString(parsed.session_id) ||
-    asString(parsed.sessionId) ||
-    asString(parsed.sessionID) ||
-    asString(parsed.checkpoint_id) ||
-    asString(parsed.thread_id)
-  );
-}
-
-function readUsage(parsed: Record<string, unknown>) {
-  const usage = asRecord(parsed.usage) ?? asRecord(parsed.usageMetadata);
-  const usageMetadata = asRecord(usage?.usageMetadata);
-  const source = usageMetadata ?? usage ?? {};
-  return {
-    inputTokens: asNumber(source.input_tokens, asNumber(source.inputTokens, asNumber(source.promptTokenCount))),
-    outputTokens: asNumber(source.output_tokens, asNumber(source.outputTokens, asNumber(source.candidatesTokenCount))),
-    cachedTokens: asNumber(
-      source.cached_input_tokens,
-      asNumber(source.cachedInputTokens, asNumber(source.cachedContentTokenCount)),
-    ),
-  };
-}
-
-export function parseGeminiStdoutLine(line: string, ts: string): TranscriptEntry[] {
-  const parsed = asRecord(safeJsonParse(line));
-  if (!parsed) {
-    return [{ kind: "stdout", ts, text: line }];
-  }
-
-  const type = asString(parsed.type);
-
-  if (type === "system") {
-    const subtype = asString(parsed.subtype);
-    if (subtype === "init") {
-      const sessionId = readSessionId(parsed);
-      return [{ kind: "init", ts, model: asString(parsed.model, "gemini"), sessionId }];
-    }
-    if (subtype === "error") {
-      const text = errorText(parsed.error ?? parsed.message ?? parsed.detail);
-      return [{ kind: "stderr", ts, text: text || "error" }];
-    }
-    return [{ kind: "system", ts, text: `system: ${subtype || "event"}` }];
-  }
-
-  if (type === "assistant") {
-    return parseAssistantMessage(parsed.message, ts);
-  }
-
-  if (type === "user") {
-    return collectTextEntries(parsed.message, ts, "user");
-  }
-
-  if (type === "thinking") {
-    const text = asString(parsed.text).trim() || asString(asRecord(parsed.delta)?.text).trim();
-    return text ? [{ kind: "thinking", ts, text }] : [];
-  }
-
-  if (type === "tool_call") {
-    return parseTopLevelToolEvent(parsed, ts);
-  }
-
-  if (type === "result") {
-    const usage = readUsage(parsed);
-    const errors = parsed.is_error === true
-      ? [errorText(parsed.error ?? parsed.message ?? parsed.result)].filter(Boolean)
-      : [];
-    return [{
-      kind: "result",
-      ts,
-      text: asString(parsed.result) || asString(parsed.text) || asString(parsed.response),
-      inputTokens: usage.inputTokens,
-      outputTokens: usage.outputTokens,
-      cachedTokens: usage.cachedTokens,
-      costUsd: asNumber(parsed.total_cost_usd, asNumber(parsed.cost_usd, asNumber(parsed.cost))),
-      subtype: asString(parsed.subtype, "result"),
-      isError: parsed.is_error === true,
-      errors,
-    }];
-  }
-
-  if (type === "error") {
-    const text = errorText(parsed.error ?? parsed.message ?? parsed.detail);
-    return [{ kind: "stderr", ts, text: text || "error" }];
-  }
-
-  return [{ kind: "stdout", ts, text: line }];
-}

packages/adapters/gemini-local/tsconfig.json

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

packages/adapters/openclaw-gateway/CHANGELOG.md

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

packages/adapters/openclaw-gateway/package.json

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

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

@@ -1069,6 +1069,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
 
   const agentParams: Record<string, unknown> = {
     ...payloadTemplate,
+    paperclip: paperclipPayload,
     message,
     sessionKey,
     idempotencyKey: ctx.runId,

packages/adapters/openclaw-gateway/tsconfig.json

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

packages/adapters/opencode-local/CHANGELOG.md

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

packages/adapters/opencode-local/package.json

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

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

@@ -50,7 +50,6 @@ function parseToolUse(parsed: Record<string, unknown>, ts: string): TranscriptEn
     kind: "tool_call",
     ts,
     name: toolName,
-    toolUseId: asString(part.callID) || asString(part.id) || undefined,
     input,
   };
 

packages/adapters/opencode-local/tsconfig.json

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

packages/adapters/pi-local/CHANGELOG.md

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

packages/adapters/pi-local/package.json

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

packages/adapters/pi-local/tsconfig.json

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

packages/db/CHANGELOG.md

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

packages/db/package.json

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

packages/db/src/migrate.ts

@@ -1,29 +1,21 @@
 import { applyPendingMigrations, inspectMigrations } from "./client.js";
-import { resolveMigrationConnection } from "./migration-runtime.js";
 
-async function main(): Promise<void> {
-  const resolved = await resolveMigrationConnection();
+const url = process.env.DATABASE_URL;
 
-  console.log(`Migrating database via ${resolved.source}`);
-
-  try {
-    const before = await inspectMigrations(resolved.connectionString);
-    if (before.status === "upToDate") {
-      console.log("No pending migrations");
-      return;
-    }
-
-    console.log(`Applying ${before.pendingMigrations.length} pending migration(s)...`);
-    await applyPendingMigrations(resolved.connectionString);
-
-    const after = await inspectMigrations(resolved.connectionString);
-    if (after.status !== "upToDate") {
-      throw new Error(`Migrations incomplete: ${after.pendingMigrations.join(", ")}`);
-    }
-    console.log("Migrations complete");
-  } finally {
-    await resolved.stop();
-  }
+if (!url) {
+  throw new Error("DATABASE_URL is required for db:migrate");
 }
 
-await main();
+const before = await inspectMigrations(url);
+if (before.status === "upToDate") {
+  console.log("No pending migrations");
+} else {
+  console.log(`Applying ${before.pendingMigrations.length} pending migration(s)...`);
+  await applyPendingMigrations(url);
+
+  const after = await inspectMigrations(url);
+  if (after.status !== "upToDate") {
+    throw new Error(`Migrations incomplete: ${after.pendingMigrations.join(", ")}`);
+  }
+  console.log("Migrations complete");
+}

packages/db/src/migration-runtime.ts

@@ -1,134 +0,0 @@
-import { existsSync, readFileSync, rmSync } from "node:fs";
-import { createRequire } from "node:module";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { ensurePostgresDatabase } from "./client.js";
-import { resolveDatabaseTarget } from "./runtime-config.js";
-
-type EmbeddedPostgresInstance = {
-  initialise(): Promise<void>;
-  start(): Promise<void>;
-  stop(): Promise<void>;
-};
-
-type EmbeddedPostgresCtor = new (opts: {
-  databaseDir: string;
-  user: string;
-  password: string;
-  port: number;
-  persistent: boolean;
-  onLog?: (message: unknown) => void;
-  onError?: (message: unknown) => void;
-}) => EmbeddedPostgresInstance;
-
-export type MigrationConnection = {
-  connectionString: string;
-  source: string;
-  stop: () => Promise<void>;
-};
-
-function readRunningPostmasterPid(postmasterPidFile: string): number | null {
-  if (!existsSync(postmasterPidFile)) return null;
-  try {
-    const pid = Number(readFileSync(postmasterPidFile, "utf8").split("\n")[0]?.trim());
-    if (!Number.isInteger(pid) || pid <= 0) return null;
-    process.kill(pid, 0);
-    return pid;
-  } catch {
-    return null;
-  }
-}
-
-function readPidFilePort(postmasterPidFile: string): number | null {
-  if (!existsSync(postmasterPidFile)) return null;
-  try {
-    const lines = readFileSync(postmasterPidFile, "utf8").split("\n");
-    const port = Number(lines[3]?.trim());
-    return Number.isInteger(port) && port > 0 ? port : null;
-  } catch {
-    return null;
-  }
-}
-
-async function loadEmbeddedPostgresCtor(): Promise<EmbeddedPostgresCtor> {
-  const require = createRequire(import.meta.url);
-  const resolveCandidates = [
-    path.resolve(fileURLToPath(new URL("../..", import.meta.url))),
-    path.resolve(fileURLToPath(new URL("../../server", import.meta.url))),
-    path.resolve(fileURLToPath(new URL("../../cli", import.meta.url))),
-    process.cwd(),
-  ];
-
-  try {
-    const resolvedModulePath = require.resolve("embedded-postgres", { paths: resolveCandidates });
-    const mod = await import(pathToFileURL(resolvedModulePath).href);
-    return mod.default as EmbeddedPostgresCtor;
-  } catch {
-    throw new Error(
-      "Embedded PostgreSQL support requires dependency `embedded-postgres`. Reinstall dependencies and try again.",
-    );
-  }
-}
-
-async function ensureEmbeddedPostgresConnection(
-  dataDir: string,
-  preferredPort: number,
-): Promise<MigrationConnection> {
-  const EmbeddedPostgres = await loadEmbeddedPostgresCtor();
-  const postmasterPidFile = path.resolve(dataDir, "postmaster.pid");
-  const runningPid = readRunningPostmasterPid(postmasterPidFile);
-  const runningPort = readPidFilePort(postmasterPidFile);
-
-  if (runningPid) {
-    const port = runningPort ?? preferredPort;
-    const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${port}/postgres`;
-    await ensurePostgresDatabase(adminConnectionString, "paperclip");
-    return {
-      connectionString: `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`,
-      source: `embedded-postgres@${port}`,
-      stop: async () => {},
-    };
-  }
-
-  const instance = new EmbeddedPostgres({
-    databaseDir: dataDir,
-    user: "paperclip",
-    password: "paperclip",
-    port: preferredPort,
-    persistent: true,
-    onLog: () => {},
-    onError: () => {},
-  });
-
-  if (!existsSync(path.resolve(dataDir, "PG_VERSION"))) {
-    await instance.initialise();
-  }
-  if (existsSync(postmasterPidFile)) {
-    rmSync(postmasterPidFile, { force: true });
-  }
-  await instance.start();
-
-  const adminConnectionString = `postgres://paperclip:paperclip@127.0.0.1:${preferredPort}/postgres`;
-  await ensurePostgresDatabase(adminConnectionString, "paperclip");
-
-  return {
-    connectionString: `postgres://paperclip:paperclip@127.0.0.1:${preferredPort}/paperclip`,
-    source: `embedded-postgres@${preferredPort}`,
-    stop: async () => {
-      await instance.stop();
-    },
-  };
-}
-
-export async function resolveMigrationConnection(): Promise<MigrationConnection> {
-  const target = resolveDatabaseTarget();
-  if (target.mode === "postgres") {
-    return {
-      connectionString: target.connectionString,
-      source: target.source,
-      stop: async () => {},
-    };
-  }
-
-  return ensureEmbeddedPostgresConnection(target.dataDir, target.port);
-}

packages/db/src/migration-status.ts

@@ -1,45 +0,0 @@
-import { inspectMigrations } from "./client.js";
-import { resolveMigrationConnection } from "./migration-runtime.js";
-
-const jsonMode = process.argv.includes("--json");
-
-async function main(): Promise<void> {
-  const connection = await resolveMigrationConnection();
-
-  try {
-    const state = await inspectMigrations(connection.connectionString);
-    const payload =
-      state.status === "upToDate"
-        ? {
-            source: connection.source,
-            status: "upToDate" as const,
-            tableCount: state.tableCount,
-            pendingMigrations: [] as string[],
-          }
-        : {
-            source: connection.source,
-            status: "needsMigrations" as const,
-            tableCount: state.tableCount,
-            pendingMigrations: state.pendingMigrations,
-            reason: state.reason,
-          };
-
-    if (jsonMode) {
-      console.log(JSON.stringify(payload));
-      return;
-    }
-
-    if (payload.status === "upToDate") {
-      console.log(`Database is up to date via ${payload.source}`);
-      return;
-    }
-
-    console.log(
-      `Pending migrations via ${payload.source}: ${payload.pendingMigrations.join(", ")}`,
-    );
-  } finally {
-    await connection.stop();
-  }
-}
-
-await main();

packages/db/src/runtime-config.test.ts

@@ -1,108 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { resolveDatabaseTarget } from "./runtime-config.js";
-
-const ORIGINAL_CWD = process.cwd();
-const ORIGINAL_ENV = { ...process.env };
-
-function writeJson(filePath: string, value: unknown) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, JSON.stringify(value, null, 2));
-}
-
-function writeText(filePath: string, value: string) {
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
-  fs.writeFileSync(filePath, value);
-}
-
-afterEach(() => {
-  process.chdir(ORIGINAL_CWD);
-  for (const key of Object.keys(process.env)) {
-    if (!(key in ORIGINAL_ENV)) delete process.env[key];
-  }
-  for (const [key, value] of Object.entries(ORIGINAL_ENV)) {
-    if (value === undefined) delete process.env[key];
-    else process.env[key] = value;
-  }
-});
-
-describe("resolveDatabaseTarget", () => {
-  it("uses DATABASE_URL from process env first", () => {
-    process.env.DATABASE_URL = "postgres://env-user:env-pass@db.example.com:5432/paperclip";
-
-    const target = resolveDatabaseTarget();
-
-    expect(target).toMatchObject({
-      mode: "postgres",
-      connectionString: "postgres://env-user:env-pass@db.example.com:5432/paperclip",
-      source: "DATABASE_URL",
-    });
-  });
-
-  it("uses DATABASE_URL from repo-local .paperclip/.env", () => {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-runtime-"));
-    const projectDir = path.join(tempDir, "repo");
-    fs.mkdirSync(projectDir, { recursive: true });
-    process.chdir(projectDir);
-    delete process.env.PAPERCLIP_CONFIG;
-    writeJson(path.join(projectDir, ".paperclip", "config.json"), {
-      database: { mode: "embedded-postgres", embeddedPostgresPort: 54329 },
-    });
-    writeText(
-      path.join(projectDir, ".paperclip", ".env"),
-      'DATABASE_URL="postgres://file-user:file-pass@db.example.com:6543/paperclip"\n',
-    );
-
-    const target = resolveDatabaseTarget();
-
-    expect(target).toMatchObject({
-      mode: "postgres",
-      connectionString: "postgres://file-user:file-pass@db.example.com:6543/paperclip",
-      source: "paperclip-env",
-    });
-  });
-
-  it("uses config postgres connection string when configured", () => {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-runtime-"));
-    const configPath = path.join(tempDir, "instance", "config.json");
-    process.env.PAPERCLIP_CONFIG = configPath;
-    writeJson(configPath, {
-      database: {
-        mode: "postgres",
-        connectionString: "postgres://cfg-user:cfg-pass@db.example.com:5432/paperclip",
-      },
-    });
-
-    const target = resolveDatabaseTarget();
-
-    expect(target).toMatchObject({
-      mode: "postgres",
-      connectionString: "postgres://cfg-user:cfg-pass@db.example.com:5432/paperclip",
-      source: "config.database.connectionString",
-    });
-  });
-
-  it("falls back to embedded postgres settings from config", () => {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-runtime-"));
-    const configPath = path.join(tempDir, "instance", "config.json");
-    process.env.PAPERCLIP_CONFIG = configPath;
-    writeJson(configPath, {
-      database: {
-        mode: "embedded-postgres",
-        embeddedPostgresDataDir: "~/paperclip-test-db",
-        embeddedPostgresPort: 55444,
-      },
-    });
-
-    const target = resolveDatabaseTarget();
-
-    expect(target).toMatchObject({
-      mode: "embedded-postgres",
-      dataDir: path.resolve(os.homedir(), "paperclip-test-db"),
-      port: 55444,
-      source: "embedded-postgres@55444",
-    });
-  });
-});

packages/db/src/runtime-config.ts

@@ -1,267 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-const DEFAULT_INSTANCE_ID = "default";
-const CONFIG_BASENAME = "config.json";
-const ENV_BASENAME = ".env";
-const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
-
-type PartialConfig = {
-  database?: {
-    mode?: "embedded-postgres" | "postgres";
-    connectionString?: string;
-    embeddedPostgresDataDir?: string;
-    embeddedPostgresPort?: number;
-    pgliteDataDir?: string;
-    pglitePort?: number;
-  };
-};
-
-export type ResolvedDatabaseTarget =
-  | {
-      mode: "postgres";
-      connectionString: string;
-      source: "DATABASE_URL" | "paperclip-env" | "config.database.connectionString";
-      configPath: string;
-      envPath: string;
-    }
-  | {
-      mode: "embedded-postgres";
-      dataDir: string;
-      port: number;
-      source: `embedded-postgres@${number}`;
-      configPath: string;
-      envPath: string;
-    };
-
-function expandHomePrefix(value: string): string {
-  if (value === "~") return os.homedir();
-  if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
-  return value;
-}
-
-function resolvePaperclipHomeDir(): string {
-  const envHome = process.env.PAPERCLIP_HOME?.trim();
-  if (envHome) return path.resolve(expandHomePrefix(envHome));
-  return path.resolve(os.homedir(), ".paperclip");
-}
-
-function resolvePaperclipInstanceId(): string {
-  const raw = process.env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_INSTANCE_ID;
-  if (!INSTANCE_ID_RE.test(raw)) {
-    throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
-  }
-  return raw;
-}
-
-function resolveDefaultConfigPath(): string {
-  return path.resolve(
-    resolvePaperclipHomeDir(),
-    "instances",
-    resolvePaperclipInstanceId(),
-    CONFIG_BASENAME,
-  );
-}
-
-function resolveDefaultEmbeddedPostgresDir(): string {
-  return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "db");
-}
-
-function resolveHomeAwarePath(value: string): string {
-  return path.resolve(expandHomePrefix(value));
-}
-
-function findConfigFileFromAncestors(startDir: string): string | null {
-  let currentDir = path.resolve(startDir);
-
-  while (true) {
-    const candidate = path.resolve(currentDir, ".paperclip", CONFIG_BASENAME);
-    if (existsSync(candidate)) return candidate;
-
-    const nextDir = path.resolve(currentDir, "..");
-    if (nextDir === currentDir) return null;
-    currentDir = nextDir;
-  }
-}
-
-function resolvePaperclipConfigPath(): string {
-  if (process.env.PAPERCLIP_CONFIG?.trim()) {
-    return path.resolve(process.env.PAPERCLIP_CONFIG.trim());
-  }
-  return findConfigFileFromAncestors(process.cwd()) ?? resolveDefaultConfigPath();
-}
-
-function resolvePaperclipEnvPath(configPath: string): string {
-  return path.resolve(path.dirname(configPath), ENV_BASENAME);
-}
-
-function parseEnvFile(contents: string): Record<string, string> {
-  const entries: Record<string, string> = {};
-
-  for (const rawLine of contents.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith("#")) continue;
-
-    const match = rawLine.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
-    if (!match) continue;
-
-    const [, key, rawValue] = match;
-    const value = rawValue.trim();
-    if (!value) {
-      entries[key] = "";
-      continue;
-    }
-
-    if (
-      (value.startsWith("\"") && value.endsWith("\"")) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      entries[key] = value.slice(1, -1);
-      continue;
-    }
-
-    entries[key] = value.replace(/\s+#.*$/, "").trim();
-  }
-
-  return entries;
-}
-
-function readEnvEntries(envPath: string): Record<string, string> {
-  if (!existsSync(envPath)) return {};
-  return parseEnvFile(readFileSync(envPath, "utf8"));
-}
-
-function migrateLegacyConfig(raw: unknown): PartialConfig | null {
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
-
-  const config = { ...(raw as Record<string, unknown>) };
-  const databaseRaw = config.database;
-  if (typeof databaseRaw !== "object" || databaseRaw === null || Array.isArray(databaseRaw)) {
-    return config;
-  }
-
-  const database = { ...(databaseRaw as Record<string, unknown>) };
-  if (database.mode === "pglite") {
-    database.mode = "embedded-postgres";
-
-    if (
-      typeof database.embeddedPostgresDataDir !== "string" &&
-      typeof database.pgliteDataDir === "string"
-    ) {
-      database.embeddedPostgresDataDir = database.pgliteDataDir;
-    }
-    if (
-      typeof database.embeddedPostgresPort !== "number" &&
-      typeof database.pglitePort === "number" &&
-      Number.isFinite(database.pglitePort)
-    ) {
-      database.embeddedPostgresPort = database.pglitePort;
-    }
-  }
-
-  config.database = database;
-  return config as PartialConfig;
-}
-
-function asPositiveInt(value: unknown): number | null {
-  if (typeof value !== "number" || !Number.isFinite(value)) return null;
-  const rounded = Math.trunc(value);
-  return rounded > 0 ? rounded : null;
-}
-
-function readConfig(configPath: string): PartialConfig | null {
-  if (!existsSync(configPath)) return null;
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(readFileSync(configPath, "utf8"));
-  } catch (err) {
-    throw new Error(
-      `Failed to parse config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
-
-  const migrated = migrateLegacyConfig(parsed);
-  if (migrated === null || typeof migrated !== "object" || Array.isArray(migrated)) {
-    throw new Error(`Invalid config at ${configPath}: expected a JSON object`);
-  }
-
-  const database =
-    typeof migrated.database === "object" &&
-    migrated.database !== null &&
-    !Array.isArray(migrated.database)
-      ? migrated.database
-      : undefined;
-
-  return {
-    database: database
-      ? {
-          mode: database.mode === "postgres" ? "postgres" : "embedded-postgres",
-          connectionString:
-            typeof database.connectionString === "string" ? database.connectionString : undefined,
-          embeddedPostgresDataDir:
-            typeof database.embeddedPostgresDataDir === "string"
-              ? database.embeddedPostgresDataDir
-              : undefined,
-          embeddedPostgresPort: asPositiveInt(database.embeddedPostgresPort) ?? undefined,
-          pgliteDataDir: typeof database.pgliteDataDir === "string" ? database.pgliteDataDir : undefined,
-          pglitePort: asPositiveInt(database.pglitePort) ?? undefined,
-        }
-      : undefined,
-  };
-}
-
-export function resolveDatabaseTarget(): ResolvedDatabaseTarget {
-  const configPath = resolvePaperclipConfigPath();
-  const envPath = resolvePaperclipEnvPath(configPath);
-  const envEntries = readEnvEntries(envPath);
-
-  const envUrl = process.env.DATABASE_URL?.trim();
-  if (envUrl) {
-    return {
-      mode: "postgres",
-      connectionString: envUrl,
-      source: "DATABASE_URL",
-      configPath,
-      envPath,
-    };
-  }
-
-  const fileEnvUrl = envEntries.DATABASE_URL?.trim();
-  if (fileEnvUrl) {
-    return {
-      mode: "postgres",
-      connectionString: fileEnvUrl,
-      source: "paperclip-env",
-      configPath,
-      envPath,
-    };
-  }
-
-  const config = readConfig(configPath);
-  const connectionString = config?.database?.connectionString?.trim();
-  if (config?.database?.mode === "postgres" && connectionString) {
-    return {
-      mode: "postgres",
-      connectionString,
-      source: "config.database.connectionString",
-      configPath,
-      envPath,
-    };
-  }
-
-  const port = config?.database?.embeddedPostgresPort ?? 54329;
-  const dataDir = resolveHomeAwarePath(
-    config?.database?.embeddedPostgresDataDir ?? resolveDefaultEmbeddedPostgresDir(),
-  );
-
-  return {
-    mode: "embedded-postgres",
-    dataDir,
-    port,
-    source: `embedded-postgres@${port}`,
-    configPath,
-    envPath,
-  };
-}

packages/db/tsconfig.json

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

packages/shared/CHANGELOG.md

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

packages/shared/package.json

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

packages/shared/src/constants.ts

@@ -26,7 +26,6 @@ export const AGENT_ADAPTER_TYPES = [
   "http",
   "claude_local",
   "codex_local",
-  "gemini_local",
   "opencode_local",
   "pi_local",
   "cursor",

packages/shared/src/index.ts

@@ -99,7 +99,6 @@ export type {
   AgentRuntimeState,
   AgentTaskSession,
   AgentWakeupRequest,
-  InstanceSchedulerHeartbeatAgent,
   LiveEvent,
   DashboardSummary,
   ActivityEvent,

packages/shared/src/types/dashboard.ts

@@ -18,4 +18,5 @@ export interface DashboardSummary {
     monthUtilizationPercent: number;
   };
   pendingApprovals: number;
+  staleTasks: number;
 }

packages/shared/src/types/heartbeat.ts

@@ -1,6 +1,4 @@
 import type {
-  AgentRole,
-  AgentStatus,
   HeartbeatInvocationSource,
   HeartbeatRunStatus,
   WakeupTriggerDetail,
@@ -107,20 +105,3 @@ export interface AgentWakeupRequest {
   createdAt: Date;
   updatedAt: Date;
 }
-
-export interface InstanceSchedulerHeartbeatAgent {
-  id: string;
-  companyId: string;
-  companyName: string;
-  companyIssuePrefix: string;
-  agentName: string;
-  agentUrlKey: string;
-  role: AgentRole;
-  title: string | null;
-  status: AgentStatus;
-  adapterType: string;
-  intervalSec: number;
-  heartbeatEnabled: boolean;
-  schedulerActive: boolean;
-  lastHeartbeatAt: Date | null;
-}

packages/shared/src/types/index.ts

@@ -48,7 +48,6 @@ export type {
   AgentRuntimeState,
   AgentTaskSession,
   AgentWakeupRequest,
-  InstanceSchedulerHeartbeatAgent,
 } from "./heartbeat.js";
 export type { LiveEvent } from "./live.js";
 export type { DashboardSummary } from "./dashboard.js";

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

@@ -7,8 +7,6 @@ export interface ExecutionWorkspaceStrategy {
   baseRef?: string | null;
   branchTemplate?: string | null;
   worktreeParentDir?: string | null;
-  provisionCommand?: string | null;
-  teardownCommand?: string | null;
 }
 
 export interface ProjectExecutionWorkspacePolicy {

packages/shared/src/validators/issue.ts

@@ -7,8 +7,6 @@ const executionWorkspaceStrategySchema = z
     baseRef: z.string().optional().nullable(),
     branchTemplate: z.string().optional().nullable(),
     worktreeParentDir: z.string().optional().nullable(),
-    provisionCommand: z.string().optional().nullable(),
-    teardownCommand: z.string().optional().nullable(),
   })
   .strict();
 

packages/shared/src/validators/project.ts

@@ -7,8 +7,6 @@ const executionWorkspaceStrategySchema = z
     baseRef: z.string().optional().nullable(),
     branchTemplate: z.string().optional().nullable(),
     worktreeParentDir: z.string().optional().nullable(),
-    provisionCommand: z.string().optional().nullable(),
-    teardownCommand: z.string().optional().nullable(),
   })
   .strict();
 

packages/shared/tsconfig.json

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

pnpm-lock.yaml

@@ -14,9 +14,6 @@ importers:
       '@playwright/test':
         specifier: ^1.58.2
         version: 1.58.2
-      cross-env:
-        specifier: ^10.1.0
-        version: 10.1.0
       esbuild:
         specifier: ^0.27.3
         version: 0.27.3
@@ -41,9 +38,6 @@ importers:
       '@paperclipai/adapter-cursor-local':
         specifier: workspace:*
         version: link:../packages/adapters/cursor-local
-      '@paperclipai/adapter-gemini-local':
-        specifier: workspace:*
-        version: link:../packages/adapters/gemini-local
       '@paperclipai/adapter-openclaw-gateway':
         specifier: workspace:*
         version: link:../packages/adapters/openclaw-gateway
@@ -74,9 +68,6 @@ importers:
       drizzle-orm:
         specifier: 0.38.4
         version: 0.38.4(@electric-sql/pglite@0.3.15)(@types/react@19.2.14)(kysely@0.28.11)(pg@8.18.0)(postgres@3.4.8)(react@19.2.4)
-      embedded-postgres:
-        specifier: ^18.1.0-beta.16
-        version: 18.1.0-beta.16
       picocolors:
         specifier: ^1.1.1
         version: 1.1.1
@@ -148,22 +139,6 @@ importers:
         specifier: ^5.7.3
         version: 5.9.3
 
-  packages/adapters/gemini-local:
-    dependencies:
-      '@paperclipai/adapter-utils':
-        specifier: workspace:*
-        version: link:../../adapter-utils
-      picocolors:
-        specifier: ^1.1.1
-        version: 1.1.1
-    devDependencies:
-      '@types/node':
-        specifier: ^24.6.0
-        version: 24.12.0
-      typescript:
-        specifier: ^5.7.3
-        version: 5.9.3
-
   packages/adapters/openclaw-gateway:
     dependencies:
       '@paperclipai/adapter-utils':
@@ -270,9 +245,6 @@ importers:
       '@paperclipai/adapter-cursor-local':
         specifier: workspace:*
         version: link:../packages/adapters/cursor-local
-      '@paperclipai/adapter-gemini-local':
-        specifier: workspace:*
-        version: link:../packages/adapters/gemini-local
       '@paperclipai/adapter-openclaw-gateway':
         specifier: workspace:*
         version: link:../packages/adapters/openclaw-gateway
@@ -349,9 +321,6 @@ importers:
       '@types/ws':
         specifier: ^8.18.1
         version: 8.18.1
-      cross-env:
-        specifier: ^10.1.0
-        version: 10.1.0
       supertest:
         specifier: ^7.0.0
         version: 7.2.2
@@ -391,9 +360,6 @@ importers:
       '@paperclipai/adapter-cursor-local':
         specifier: workspace:*
         version: link:../packages/adapters/cursor-local
-      '@paperclipai/adapter-gemini-local':
-        specifier: workspace:*
-        version: link:../packages/adapters/gemini-local
       '@paperclipai/adapter-openclaw-gateway':
         specifier: workspace:*
         version: link:../packages/adapters/openclaw-gateway
@@ -1023,9 +989,6 @@ packages:
     cpu: [x64]
     os: [win32]
 
-  '@epic-web/invariant@1.0.0':
-    resolution: {integrity: sha512-lrTPqgvfFQtR/eY/qkIzp98OGdNJu0m5ji3q/nJI8v3SXkRKEnWiOxMmbvcSoAIzv/cGiuvRy57k4suKQSAdwA==}
-
   '@esbuild-kit/core-utils@3.3.2':
     resolution: {integrity: sha512-sPRAnw9CdSsRmEtnsl2WXWdyquogVpB3yZ3dgwJfe8zrOzTsV7cJvmwrKVa+0ma5BoiGJ+BoqkMvawbayKUsqQ==}
     deprecated: 'Merged into tsx: https://tsx.is'
@@ -3461,11 +3424,6 @@ packages:
   crelt@1.0.6:
     resolution: {integrity: sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g==}
 
-  cross-env@10.1.0:
-    resolution: {integrity: sha512-GsYosgnACZTADcmEyJctkJIoqAhHjttw7RsFrVoJNXbsWWqaq6Ym+7kZjq6mS45O0jij6vtiReppKQEtqWy6Dw==}
-    engines: {node: '>=20'}
-    hasBin: true
-
   cross-spawn@7.0.6:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
@@ -6783,8 +6741,6 @@ snapshots:
   '@embedded-postgres/windows-x64@18.1.0-beta.16':
     optional: true
 
-  '@epic-web/invariant@1.0.0': {}
-
   '@esbuild-kit/core-utils@3.3.2':
     dependencies:
       esbuild: 0.18.20
@@ -9299,11 +9255,6 @@ snapshots:
 
   crelt@1.0.6: {}
 
-  cross-env@10.1.0:
-    dependencies:
-      '@epic-web/invariant': 1.0.0
-      cross-spawn: 7.0.6
-
   cross-spawn@7.0.6:
     dependencies:
       path-key: 3.1.1

releases/v0.3.0.md

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