## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Pipelines are a control-plane workflow surface where operators need
confidence that setup, intake, board movement, review, and learning
flows keep working.
> - The tutorial flow is broad enough that regressions can slip through
unit tests when UI state, route behavior, and workflow fixtures drift
apart.
> - End-to-end coverage gives reviewers a realistic smoke path through
the pipelines tutorial experience.
> - This pull request ports the pipelines tutorial flow into Playwright
and updates the variable flow covered by the scenario.
> - The benefit is stronger browser-level regression coverage for a
high-value onboarding/workflow path.
## Linked Issues or Issue Description
No public GitHub issue exists. Inline feature request:
**Subsystem affected**
Cross-cutting: `tests/e2e`, server startup, and the pipelines UI
workflow.
**Problem or motivation**
The pipelines tutorial flow lacked focused browser-level regression
coverage for setup, intake, board movement, detail/review surfaces, and
learning flow behavior. This left a broad user-facing workflow dependent
on narrower unit coverage.
**Proposed solution**
Add a Playwright spec that boots a throwaway Paperclip instance and
exercises the tutorial flow across setup, intake, board movement, item
detail, review queue, learnings, agent fan-out, drift acknowledgement
gates, child-terminal gates, and stale approvals.
**Alternatives considered**
Unit tests alone are faster but do not validate the integrated browser
workflow. A release-smoke-only path would be broader than necessary for
this tutorial-specific coverage.
**Roadmap alignment**
This supports the roadmap theme of easier onboarding and stronger
first-run confidence without adding a new core feature surface.
**Additional context**
The local host used for this PR is missing Chromium’s `libatk-1.0.so.0`
dependency, so the full browser run needs CI or a machine with
Playwright system dependencies installed.
## What Changed
- Added a Playwright e2e spec covering the pipelines tutorial flow.
- Covered agent fan-out, drift acknowledgement gates, child-terminal
gates, stale approvals, setup/intake, board movement, item detail,
review queue, and learnings.
- Added Playwright config support needed by the new tutorial flow.
- Updated the tutorial variable flow assertions in the ported spec.
## Verification
- Attempted
`/srv/paperclip/home/paperclipai/paperclip/node_modules/.bin/playwright
test --config tests/e2e/playwright.config.ts
tests/e2e/pipelines-tutorial-flow.spec.ts`
- Local result: the throwaway Paperclip server booted and `covers agent
fan-out, drift acknowledgement gates, child-terminal gates, and stale
approvals` passed.
- Local blocker: the second Chromium test failed before executing
because this host is missing the Playwright system library
`libatk-1.0.so.0`. CI should run this on an image with browser
dependencies installed.
## Risks
Medium risk for CI duration/flakiness because this adds browser-level
coverage over a broad workflow. The test is intentionally scoped to one
spec file and uses the dedicated e2e config/server path.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5.5 coding agent with repository tool use and local
shell execution. Context window was not surfaced by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Watchdogs keep issue execution moving by waking agents or creating
recovery paths when work stalls.
> - Open review states should generate useful follow-up, not repeated
duplicate wake requests for the same unresolved review condition.
> - Duplicate wakes create noise and can make the control plane look
busier without increasing progress.
> - This pull request deduplicates open watchdog review wake scheduling
and covers the behavior with scheduler tests.
> - The benefit is cleaner review wake behavior and fewer redundant
agent runs.
## Linked Issues or Issue Description
No public GitHub issue exists. Inline bug report:
**Pre-submission checklist**
- [x] I have searched existing open and closed issues and this is not a
duplicate.
- [x] I am on the latest released version of Paperclip (or can reproduce
on `master`).
- [x] I have confirmed the error originates in Paperclip itself — not in
my agent adapter, API provider, or local configuration.
**What happened?**
Watchdog scheduling could enqueue duplicate open review wake requests
while the same unresolved review condition was already pending.
**Expected behavior**
A watchdog should avoid scheduling redundant review wakes for the same
unresolved condition while preserving legitimate wake paths.
**Steps to reproduce**
1. Create an issue state that requires an open watchdog review wake.
2. Run the watchdog scheduler once and observe a wake request.
3. Run the scheduler again before resolving the original review
condition.
4. Observe whether a duplicate wake is created.
**Paperclip version or commit**
`master` at the PR base.
**Deployment mode**
Local dev (`pnpm dev`) and server deployments running watchdog
scheduling.
**Installation method**
Built from source (`pnpm dev` / `pnpm build`).
**Agent adapter(s) involved**
- [x] Not adapter-specific (core bug)
**Database mode**
Not database-related beyond scheduler persistence.
**Access context**
Agent wake scheduling and board-visible review state.
**Relevant logs or output**
Covered by the added scheduler regression test.
**Relevant config (if applicable)**
Not applicable.
**Additional context**
This suppresses duplicate wake scheduling only while the open review
state is still unresolved.
**Privacy checklist**
- [x] I have reviewed all pasted output for PII (usernames, file paths,
API keys, tokens, company names) and redacted where necessary.
## What Changed
- Added deduplication logic for open watchdog review wake scheduling.
- Added scheduler regression coverage for duplicate open review wake
suppression.
## Verification
- `/srv/paperclip/home/paperclipai/paperclip/node_modules/.bin/vitest
run server/src/__tests__/task-watchdogs-scheduler.test.ts`
## Risks
Low-to-medium risk. The change intentionally suppresses duplicate wake
scheduling, so reviewers should confirm no legitimate repeated wake path
depends on creating multiple open requests for the same unresolved
review state.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5.5 coding agent with repository tool use and local
shell execution. Context window was not surfaced by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Operators depend on `/api/health` and OpenAPI status surfaces to
know whether the local control plane is healthy.
> - Database backups are a safety-critical background process, but
backup failures were not represented in health responses.
> - That gap means an instance can look healthy while backup state is
stale, failing, or unavailable.
> - This pull request adds backup-health evaluation and exposes it
through the health route, server startup wiring, and OpenAPI contract.
> - The benefit is earlier operator visibility when automatic backups
stop protecting instance data.
## Linked Issues or Issue Description
No public GitHub issue exists. Inline bug report:
**Pre-submission checklist**
- [x] I have searched existing open and closed issues and this is not a
duplicate.
- [x] I am on the latest released version of Paperclip (or can reproduce
on `master`).
- [x] I have confirmed the error originates in Paperclip itself — not in
my agent adapter, API provider, or local configuration.
**What happened?**
Automatic database backup health was not included in the app health
response, so backup failures or stale backups could be missed while
`/api/health` still looked otherwise usable.
**Expected behavior**
The health endpoint should include backup-health details that let
operators identify disabled, stale, failing, or healthy backup states.
**Steps to reproduce**
1. Configure a Paperclip instance with automatic database backups.
2. Force backup status into a stale or failing state.
3. Call `/api/health` and inspect whether backup state is represented.
**Paperclip version or commit**
`master` at the PR base.
**Deployment mode**
Local dev (`pnpm dev`) and self-hosted server deployments.
**Installation method**
Built from source (`pnpm dev` / `pnpm build`).
**Agent adapter(s) involved**
- [x] Not adapter-specific (core bug)
**Database mode**
Embedded development Postgres and external Postgres backup paths.
**Access context**
Board/operator health checks.
**Relevant logs or output**
Covered by the added `server/src/__tests__/health.test.ts` cases.
**Relevant config (if applicable)**
Not applicable.
**Additional context**
This surfaces backup status only; it does not change backup execution
scheduling.
**Privacy checklist**
- [x] I have reviewed all pasted output for PII (usernames, file paths,
API keys, tokens, company names) and redacted where necessary.
## What Changed
- Added a database backup health service that classifies backup recency,
status, and failure conditions.
- Wired backup health into app/server startup and the health route
response.
- Documented the backup-health behavior in development docs and OpenAPI
output.
- Added focused health route tests for healthy, stale, disabled, and
failing backup states.
## Verification
- `/srv/paperclip/home/paperclipai/paperclip/node_modules/.bin/vitest
run server/src/__tests__/health.test.ts`
## Risks
Low-to-medium risk. This changes health response content and may affect
external health consumers that parse fields strictly. It should not
alter backup execution itself.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5.5 coding agent with repository tool use and local
shell execution. Context window was not surfaced by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The database migration layer keeps local and deployed instances
moving forward safely as schema/data contracts evolve.
> - The responsible-user backfill migration could make historical issues
look newly updated by bumping user-visible `updated_at` columns during a
backfill.
> - That timestamp churn can invalidate inbox/archive state and make old
work appear fresh even though no user-facing activity happened.
> - This pull request moves the responsible-user invariant migration
later in the current migration sequence, keeps it from touching
user-visible timestamps, and adds a repair sweep for databases that
already saw the timestamp bump.
> - The benefit is safer migration replay and regression coverage for
future backfills that might otherwise mutate visible timestamps.
## Linked Issues or Issue Description
No public GitHub issue exists. Inline bug report:
**Pre-submission checklist**
- [x] I have searched existing open and closed issues and this is not a
duplicate.
- [x] I am on the latest released version of Paperclip (or can reproduce
on `master`).
- [x] I have confirmed the error originates in Paperclip itself — not in
my agent adapter, API provider, or local configuration.
**What happened?**
A responsible-user migration backfill could update user-visible
`updated_at` columns while filling missing responsible-user data. That
makes historical issues/runs/routines appear newer even when no
user-facing activity happened.
**Expected behavior**
Responsible-user backfills should populate ownership metadata without
mutating user-visible recency fields, and databases already affected by
a timestamp sweep should be repairable.
**Steps to reproduce**
1. Start from current `master` with the responsible-user migration
sequence.
2. Apply migrations to a database containing historical issues, runs,
routines, and companies with older activity timestamps.
3. Replay the responsible-user invariant migration and inspect
user-visible `updated_at` values.
**Paperclip version or commit**
`master` at the PR base.
**Deployment mode**
Local dev (`pnpm dev`) and deployed instances using the same migrations.
**Installation method**
Built from source (`pnpm dev` / `pnpm build`).
**Agent adapter(s) involved**
- [x] Not adapter-specific (core bug)
**Database mode**
External Postgres and embedded development Postgres migration paths.
**Access context**
Board and agent-visible issue recency can both be affected.
**Relevant logs or output**
Covered by the added embedded-Postgres regression tests.
**Relevant config (if applicable)**
Not applicable.
**Additional context**
This PR adapts an extracted local migration fix onto the current master
migration sequence, where `0133` is already occupied.
**Privacy checklist**
- [x] I have reviewed all pasted output for PII (usernames, file paths,
API keys, tokens, company names) and redacted where necessary.
## What Changed
- Renumbered the responsible-user invariant migration onto the current
master migration sequence.
- Added a repair migration that detects broad timestamp sweeps and
restores safer `updated_at` values for issues, heartbeat runs, routines,
routine runs, and companies.
- Added focused embedded-Postgres regression coverage for the relocated
migration, repair migration, and updated-at backfill allowlist.
## Verification
- `pnpm --filter @paperclipai/db run check:migrations`
- `/srv/paperclip/home/paperclipai/paperclip/node_modules/.bin/vitest
run packages/db/src/client.test.ts -t "migration 0134|migration
0135|unallowlisted migration backfills"`
## Risks
Migration behavior is the main risk. The PR intentionally changes the
active migration sequence by removing the old responsible-user invariant
slot and replaying that work later with a repair migration. Reviewers
should confirm this matches the intended release/migration policy for
installations that may already have applied the earlier migration.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5.5 coding agent with repository tool use and local
shell execution. Context window was not surfaced by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents execute on isolated workspaces (git worktrees), each pinned
to a specific branch and commit at checkout time
> - When an agent's live checkout diverges from the recorded workspace
branch — either through a branch rename, a stale worktree, or a
concurrent git operation — Paperclip detects the mismatch and surfaces a
recovery card to the operator
> - But the existing recovery card showed a generic error with no
diagnostic context: it didn't display *which* branch was expected vs.
which was checked out, the commit SHAs involved, or whether the branches
share ancestry
> - Without that information operators cannot diagnose the root cause,
and the only recovery path was fully manual re-issue
> - This pull request extends `IssueRecoveryActionCard` for
`workspace_validation` / `git_worktree_branch_incoherence` recovery
kinds to render a divergence-diagnosis panel (expected branch, live
branch, short SHAs, ancestry-verdict badge, plain-language reason) and
adds a confirm-gated "Re-issue on isolated workspace" action that
creates a new task with `executionWorkspacePreference:
isolated_workspace` so the re-issued run cannot trip the same
branch-mismatch gate
> - The benefit is that operators can immediately see *why* a workspace
was declined and recover with a single click instead of having to
manually reconstruct the task
## Linked Issues or Issue Description
Refs #4757 (heartbeat re-wake doesn't reconcile working-tree HEAD
against ticket's expected branch — this PR surfaces the resulting
divergence to the operator and provides a one-click isolated re-issue
path)
Refs #8460 (workspace_validation_failed local-only project workspaces —
this PR extends the recovery card UI for this case)
**Subsystem affected:** ui/ — React + Vite board UI
**Problem or motivation:** When Paperclip records a workspace branch for
an agent run and the live checkout disagrees (diverged HEAD, renamed
branch, stale worktree), the issue recovery card surfaces a generic
`workspace_validation` error. The operator sees "run declined" but has
no visibility into the expected vs. actual branch, the relevant commit
SHAs, or whether the branches even share ancestry. There is no one-click
path to re-issue the task on a clean isolated workspace — the operator
must manually reconstruct the task from scratch.
**Proposed solution:** Extend `IssueRecoveryActionCard` to:
1. Render a divergence-diagnosis panel from the `recoveryEvidence`
field: expected branch, live branch, short SHAs for both, an
ancestry-verdict badge (`forward-only` / `diverged` / `ancestry
unknown`), and the server's `plainLanguageReason`.
2. Add Action 3 "Re-issue on isolated workspace" — a confirm-gated
button that calls `issuesApi.create` with `executionWorkspacePreference:
isolated_workspace` and `workspaceStrategy.baseRef` set to the live
branch (SHA fallback when detached). The current workspace is never
mutated.
3. Wire `onReissueIsolated` / `reissuePending` through `IssueChatThread`
→ `IssueDetail` so the operator sees an immediate success toast and is
navigated to the new task.
**Alternatives considered:** Showing divergence details only in a
tooltip (rejected — too easy to miss). Providing a "force-reset the
workspace" action (rejected — destructive, no audit trail, doesn't fix
stale-branch root cause). Isolated re-issue via isolated workspace was
the clearest safe path.
## What Changed
- `IssueRecoveryActionCard.tsx` — Added `DiagnosisPanel` sub-component
rendered for `workspace_validation` / `git_worktree_branch_incoherence`
recovery kinds: displays expected vs. live branch, short SHAs,
ancestry-verdict badge, and plain-language reason. Added Action 3
confirm-popover with `onReissueIsolated` callback and `reissuePending`
loading state. Kept existing Action 1 and Action 2 unchanged.
- `IssueChatThread.tsx` — Threaded `onReissueIsolated` and
`reissuePending` props down to `IssueRecoveryActionCard`.
- `IssueDetail.tsx` — Implemented `handleReissueIsolated`: calls
`issuesApi.create` with `executionWorkspacePreference:
isolated_workspace` + `workspaceStrategy.baseRef` derived from live
branch / SHA; shows a success toast and navigates to the new task on
completion.
- `IssueRecoveryActionCard.test.tsx` — Added 19 unit tests covering
diagnosis-panel rendering, verdict label rendering, base-ref derivation
(branch-first then detached-HEAD SHA fallback), and action gating.
## Verification
```bash
# Unit tests — 19/19 pass
pnpm vitest run ui/src/components/IssueRecoveryActionCard.test.tsx
# Typecheck — 0 new errors
pnpm typecheck
```
Manual browser validation deferred to QA — see Risks.
## Risks
- **Re-issue creates a new task** — the original task remains unchanged.
This is intentional (safe default), but operators should be aware both
tasks exist after re-issue.
- **Base-ref derivation falls back to the live HEAD SHA when detached.**
SHA-based worktrees are valid for isolated re-issue but may surprise
operators expecting a branch name.
- **Browser-level end-to-end validation not included here.** Toast,
navigation, and full create-flow are covered by integration QA in a
follow-up pass.
- **Low overall risk** — no new endpoints, no data mutations on existing
records, no PII or telemetry changes. Composes the existing
`issuesApi.create` endpoint; all new behavior is additive.
## Model Used
Claude Sonnet 4.6 (`claude-sonnet-4-6`) — Anthropic. 200k context
window, tool use, code execution. Extended thinking not used.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The issue/task orchestration subsystem tracks parent–child and
blocker–dependent relationships, forming a directed acyclic (in
intention) subtree below each root issue
> - Agents and operators have no lightweight way to inspect the
dependency and wake state across an entire issue subtree — they must
walk the tree issue-by-issue, making multiple round-trips with full
object fetches
> - A bounded, read-only subtree diagnostic endpoint lets callers
understand the health of an entire work tree (which nodes are blocked,
which are cycling, which have pending wakes) from a single authenticated
request
> - This pull request adds `GET /api/issues/:id/diagnostics/subtree`, a
depth/node/per-node capped traversal that reuses the blocker and wake
projection helpers from the companion blocker and wake diagnostics
endpoints (see Refs #9114, #9133)
> - The benefit is that platform operators, monitoring, and coaching
tooling can surface \"why is this subtree stalled?\" across all nodes
without database access or unbounded graph walks, using only data the
caller already has read permission for
## Linked Issues or Issue Description
Refs #9114 (companion blocker diagnostics endpoint — blocker projection
helpers reused here)
Refs #9133 (companion wake diagnostics endpoint — wake projection
helpers reused here)
## What Changed
- **New route** `GET /api/issues/:id/diagnostics/subtree` in
`server/src/routes/issues.ts`: returns a bounded subtree traversal
rooted at `:id`, with depth/node/per-node caps and explicit truncation
flags
- **Cycle-safe traversal**: visited-node set prevents infinite loops on
any accidental cycle in the ancestry graph
- **Per-node authorization**: each subtree node is individually filtered
through `assertIssueReadAllowed`; unauthorized nodes are omitted from
the response and do not influence aggregate counts
- **Blocker and wake reuse**: per-node blocker rows and wake events are
projected through the same helpers as #9114 and #9133 — raw wake
payloads, raw errors, activity details, and trigger detail fields are
stripped
- **Low-trust filtering**: the `mention-scoped` low-trust path redacts
node/blocker identifiers for unauthorized actors, consistent with #9133
- **Truncation reporting**: response includes `depthTruncated`,
`nodeTruncated`, and per-node `blockersTruncated`/`wakesTruncated` flags
when caps are hit
- **Shared types** in `@paperclipai/shared`:
`IssueSubtreeDiagnosticsResponse` and supporting node/blocker/wake types
exported from the shared package
- **OpenAPI tag registration** for the new route
- **API reference docs** in
`skills/paperclip/references/api-reference.md`
- **Test coverage**
(`server/src/__tests__/issue-subtree-diagnostics-routes.test.ts`,
embedded Postgres): happy path, quiet singleton (no children/blockers),
node cap truncation, mention-scoped low-trust filtering, cross-company
denial
## Verification
```bash
# Subtree diagnostics tests only
pnpm exec vitest run server/src/__tests__/issue-subtree-diagnostics-routes.test.ts
# Full diagnostics suite (blocker + wake + subtree)
pnpm exec vitest run server/src/__tests__/issue-blocker-diagnostics-routes.test.ts server/src/__tests__/issue-wake-diagnostics-routes.test.ts server/src/__tests__/issue-subtree-diagnostics-routes.test.ts
# Type-check shared and server packages
pnpm --filter @paperclipai/shared typecheck
pnpm --filter @paperclipai/server typecheck
# Whitespace / diff check
git diff --check
```
All commands passed locally (5 subtree tests, 17 total across the three
diagnostics test files).
## Risks
- **No schema or migration changes** — read-only projection over
existing relations; no DDL risk
- **Bounded traversal** — depth, node count, and per-node blocker/wake
caps prevent unbounded graph walks; truncation is reported explicitly in
the response
- **Auth boundary** — root issue read is company-scoped and checked
before the subtree is built; each subtree node is individually
authorized; cross-company access is denied at `assertCompanyAccess`
- **No raw payloads** — raw wake payload, raw error, activity details,
and trigger detail fields are stripped from all nodes, consistent with
the companion endpoints
- Low overall risk; the endpoint is additive and read-only
## Model Used
- **Provider:** Anthropic
- **Model:** Claude Sonnet 4.6 (`claude-sonnet-4-6`)
- **Tool use:** yes (file reads, edits, bash execution, Paperclip API
calls)
- **Reasoning mode:** standard (no extended thinking)
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents run inside git worktrees; the heartbeat system establishes a
workspace branch and tracks it through checkout, realization, restore,
and finalization
> - When the live git branch diverges from the recorded workspace branch
mid-change (branch incoherence), the heartbeat must fail closed with
`workspace_validation_failed` and block the source issue with a recovery
action
> - There were no embedded-Postgres tests covering this fail-closed
behavior across the three interlock call sites: fresh git-worktree
realization, persisted workspace restore, and heartbeat finalization
> - This PR adds a single test file covering all three call sites with
an embedded-Postgres heartbeat test harness and asserts the exact
fail-closed outcome and evidence fields
> - The benefit is confidence that branch-incoherence containment is
correct and regressions in the interlock chain are caught before they
silently corrupt workspace state
## Linked Issues or Issue Description
Refs: #6425 (related: enforce issue branch matches workspace on
wake/checkout)
No pre-existing public GitHub issue for this specific reproduction test
gap. The underlying problem:
**Bug / gap:** The heartbeat's branch-incoherence containment was
untested by any embedded-Postgres integration test. All three call sites
— fresh git-worktree realization, persisted workspace restore, and
finalization — could regress without detection. The fail-closed path
(`workspace_validation_failed` + source-issue block + deduped recovery
action) and the evidence fields surfaced to operators were unverified.
## What Changed
- Added
`server/src/__tests__/heartbeat-workspace-branch-containment.test.ts`
with embedded-Postgres integration tests covering:
- **Fresh git-worktree realization** — heartbeat detects branch
divergence at workspace setup and fails closed
- **Persisted workspace restore** — re-entering a previously-established
workspace with a diverged branch fails closed instead of being silently
coerced into a generic reuse-failure path
- **Heartbeat finalization** — any late-stage branch incoherence
detected at finalization fails closed
- Asserts fail-closed behavior in all three cases: run status =
`workspace_validation_failed`, source issue status = `blocked`, exactly
one deduped workspace-validation recovery action on the blocked issue,
sibling issues on same/other workspaces retain their status
- Asserts evidence completeness: `expectedBranch`, `liveBranch`,
`expectedHead`, `liveHead`, `cleanliness`, `ancestryVerdict`,
`plainLanguageReason`, and `recoveryGuidance` fields are present and
correct on the run
- Ensures release/promotion errors after setup failures are logged (not
silently swallowed), making cleanup failures observable
## Verification
```bash
pnpm exec vitest run server/src/__tests__/heartbeat-workspace-branch-containment.test.ts
pnpm --filter @paperclipai/server typecheck
```
All 3 tests pass, typecheck clean.
## Risks
Low. Test-only change — no production code paths are modified. The tests
use an embedded-Postgres harness and do not touch any shared or live
database.
## Model Used
Claude Sonnet 4.6 (`claude-sonnet-4-6`) via Claude Code — tool use mode,
standard context window.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open-source app people use to manage AI agents for
work
> - The task/issue lifecycle subsystem tracks when agents wake up, are
suppressed, or are deferred, recording each wake request in
`agent_wakeup_requests` and each defer/suppression event in
`activity_log`
> - When an agent appears stuck or doesn't resume after a dependency
resolves, there is currently no read-only API surface to inspect its
wake history — operators must query the database directly
> - Making wake history queryable via a first-class endpoint lets
operators, support, and monitoring tools diagnose "why didn't this agent
wake up?" without database access
> - This pull request adds `GET /api/issues/:id/diagnostics/wakes`,
returning a bounded 14-day/50-row projection of wake requests and
defer/suppression activity events, with a deterministic `diagnosis`
field and a `likelyReason` inference — including a Case-B inference ("no
wake enqueued because a visible blocker is not done") that reuses the
blocker readiness data from the companion blocker diagnostics endpoint
(see Refs #9114)
> - The benefit is that platform operators can answer "why is this agent
not waking up?" from a safe, read-only HTTP endpoint rather than needing
direct database access, and CI/monitoring can assert expected wake
behavior
## Linked Issues or Issue Description
Refs #9114 (companion blocker diagnostics endpoint, already merged —
this PR extends the same diagnostic surface to wake/activity history)
## What Changed
- **New route** `GET /api/issues/:id/diagnostics/wakes` in
`server/src/routes/issues.ts`: returns a bounded (14-day window, 50-row
cap) projection of `agent_wakeup_requests` rows and wake-relevant
`activity_log` rows (defer/suppression events)
- **Sanitized projection**: raw `payload`, `details`, `error`, and
`triggerDetail` fields are stripped; unknown free-form `source`,
`reason`, and `status` values are projected to `"other"` to prevent
schema bleed
- **Deterministic `diagnosis` and `likelyReason` fields**: includes
Case-B inference ("no wake enqueued — visible blocker not done") that
calls the existing blocker-readiness helper from Slice 1 (#9114) so the
wake surface can explain missing wakes caused by outstanding blockers
- **Auth**: `assertCompanyAccess` + `assertIssueReadAllowed`;
cross-company requests are denied; Case-B blocker inference filters by
caller trust level so hidden (low-trust) blockers are mentioned but not
identified
- **Types in `@paperclipai/shared`**: `IssueWakeDiagnosticsResponse`,
`WakeEvent`, `ActivityEvent` exported from the shared package
- **OpenAPI tag registration** for the new route
- **Skill reference docs** in
`skills/paperclip/references/api-reference.md` documenting the endpoint
contract
- **Test coverage**
(`server/src/__tests__/issue-wake-diagnostics-routes.test.ts`, embedded
Postgres): happy path, empty/null diagnosis, Case-B inference, low-trust
hidden blocker, cross-company denial, raw blob minimization, cap
behaviour, combined blocker+wake test run
## Verification
```bash
# Wake diagnostics tests only
pnpm exec vitest run server/src/__tests__/issue-wake-diagnostics-routes.test.ts
# Wake + blocker diagnostics together (integration)
pnpm exec vitest run server/src/__tests__/issue-blocker-diagnostics-routes.test.ts server/src/__tests__/issue-wake-diagnostics-routes.test.ts
# Type-check shared and server packages
pnpm --filter @paperclipai/shared typecheck
pnpm --filter @paperclipai/server typecheck
# Whitespace / diff check
git diff --check
```
All commands passed locally.
## Risks
- **No schema or migration changes** — this is a read-only projection
over existing tables; no DDL risk.
- **Bounded queries** — 14-day window + 50-row cap limit per call; no
unbounded scans.
- **Auth boundary** — cross-company access is denied at
`assertCompanyAccess`; Case-B inference uses the same per-node trust
filtering as the blocker endpoint so low-trust blockers are acknowledged
but not identified.
- Low overall risk; the endpoint is additive and read-only.
## Model Used
- **Provider:** Anthropic
- **Model:** Claude Sonnet 4.6 (`claude-sonnet-4-6`)
- **Tool use:** yes (file reads, edits, bash execution, Paperclip API
calls)
- **Reasoning mode:** standard (no extended thinking)
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents block each other with `blockedByIssueIds` relationships to
express dependencies
> - Users and tooling have no lightweight way to inspect *why* an issue
is blocked or whether its blockers are themselves ready to resolve
> - A read-only diagnostic endpoint over the existing blocker graph lets
callers understand dependency chains without requiring a full issue-tree
traversal
> - This pull request adds `GET /api/issues/:id/diagnostics/blockers` —
a bounded, read-only projection over each blocker's readiness state
> - The benefit is that callers can surface blocking-chain diagnosis
(e.g. "waiting on N blockers, M of which are themselves blocked") from a
single authenticated request, using only data they already have read
permission for
## Linked Issues or Issue Description
No public GitHub issue exists for this change. Feature description:
**Subsystem affected:** `server/` — REST API & orchestration services;
`packages/shared` — types, constants, validators, API paths
**Problem or motivation**
There is no API endpoint to inspect *why* an issue is blocked or to get
a per-blocker readiness summary. Clients must walk the issue graph
manually or fetch full issue objects, which requires multiple
round-trips and is expensive.
**Proposed solution**
A single `GET /api/issues/:id/diagnostics/blockers` endpoint returns a
bounded projection: root issue summary, an ordered blocker list with
per-blocker `readiness` state, and a top-level `diagnosis` field
summarizing overall blocking status. Authorization mediation omits
blockers the caller cannot read, so `diagnosis` only reflects visible
data.
**Alternatives considered**
A general graph-walk query (too broad/expensive for a targeted
diagnostic call); enriching the existing `GET /api/issues/:id` response
(too coupled to the main response shape and adds weight for callers that
do not need blocker detail).
**Roadmap alignment**
Read-only observability surface over existing data; no database schema
changes. This aligns with tooling that helps users understand dependency
state without mutating anything.
## What Changed
- Added `GET /api/issues/:id/diagnostics/blockers` route to the server
- Returns per-blocker `readiness` state and a top-level `diagnosis`
field summarizing overall blocking status
- Enforces `issue:read` authorization per-blocker: unauthorized blockers
are omitted and do not influence `diagnosis` or `readiness` values
- Added shared TypeScript response types in `@paperclipai/shared`
- Added route-level tests using embedded Postgres
- Added API documentation in the `paperclip` skill
## Verification
```sh
./node_modules/.bin/vitest run server/src/__tests__/issue-blocker-diagnostics-routes.test.ts
pnpm --filter @paperclipai/shared typecheck
pnpm --filter @paperclipai/server typecheck
```
All three commands pass locally.
## Risks
- Read-only endpoint over existing relations — no writes, no schema or
migration changes — low risk
- Authorization mediation intentionally omits unauthorized blockers from
both the list and from `diagnosis`/`readiness`; callers with partial
access will see a narrower picture than the full blocker graph
## Model Used
- Provider: Anthropic
- Model: Claude Sonnet 4.6 (`claude-sonnet-4-6`)
- Context window: 200k tokens
- Mode: Tool use, code generation, extended reasoning
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` /
`Closes: #` / `Refs: #` OR (b) described the issue in-PR following the
relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The `packages/db` module owns all database migrations via a
sequential numbering system already validated at build time
> - A recent migration introduced an O(n²) batch backfill over a large,
unindexed table — it caused the server's `listen` to block for ~5
minutes on databases with millions of rows
> - Nothing in the current CI pipeline catches large-table migration
risk patterns (DO-loop mutations, batched LIMIT mutations without
support indexes, full-table mutations, non-concurrent index creation)
before they land
> - This PR wires a new static migration-safety checker
(`check-migration-safety.ts`) into the existing `check:migrations` gate
in `packages/db/package.json`, so risky patterns fail CI before reaching
production
> - The checker baselines all historical findings already present in the
codebase, so the gate fails only on *new* unbaselined risky patterns
> - The benefit is that the specific O(n²) backfill shape (and related
patterns) will be caught at author time rather than at incident time
## Linked Issues or Issue Description
**Feature — static migration safety lint**
**Problem or motivation**
Migrations against large tables (millions of rows) have caused
production startup blocks. The root pattern is a batched `LIMIT`-based
backfill iterating via an unindexed column, making each batch a
sequential scan — O(n²) overall. No CI gate exists to flag this class of
problem before merge.
**Proposed solution**
A static SQL-level checker that scans new migration files for known
dangerous patterns against known-large tables, producing structured
findings that are either baselined (suppressed) or fail the build.
Patterns detected: `DO $$ loop` mutations on large tables without a
same-migration support index, batched `LIMIT` mutations on large tables
missing a same-migration support index, unbounded full-table mutations
(no `WHERE` clause), and `CREATE INDEX` without `CONCURRENTLY` on large
tables.
**Alternatives considered**
Runtime instrumentation (only catches issues in production), advisory
locking in migrations (doesn't prevent the pattern), per-migration code
review (doesn't scale consistently).
**Roadmap alignment**
Defensive infrastructure / operational reliability — keeps migrations
from blocking production startups. Not a user-facing feature.
## What Changed
- **`packages/db/package.json`** — extended `check:migrations` script to
run `check-migration-safety.ts` after the existing numbering check
- **`packages/db/src/check-migration-safety.ts`** — new static checker:
SQL pattern matching, rule detection for four dangerous patterns,
baseline diffing, and structured exit with findings summary
- **`packages/db/src/migration-safety-baseline.ts`** — baseline of all
existing historical findings (suppressed from failing the gate); new
migrations matching these patterns without a baseline entry will fail
- **`packages/db/src/table-size-estimates.ts`** — rough table size
estimates from the local dev database; drives `isKnownLargeTable()` used
by the safety rules
- **`packages/db/src/check-migration-safety.test.ts`** — Vitest coverage
for the O(n²) backfill failure mode, suppression via baseline, and each
rule type
## Verification
```bash
# Run the migration safety checker directly
cd packages/db
tsx src/check-migration-safety.ts
# Run tests
cd packages/db
npx vitest run src/check-migration-safety.test.ts
# Run the full migration check gate (numbering + safety)
cd packages/db
pnpm run check:migrations
```
- Tests cover the core O(n²) backfill pattern (the motivating incident),
baseline suppression, and all four rule types
- `check:migrations` now exits non-zero for any new unbaselined
large-table migration risk pattern
## Risks
- **False positives:** Table-size estimates are from a local dev
database snapshot — a table small in dev but large in production would
be missed. Best-effort heuristic.
- **Baseline drift:** If a baselined finding's SQL changes
significantly, the baseline ID (content-hash-based) will no longer match
and the finding will re-surface. Intentional but may surprise authors
doing incremental fixes.
- **SQL parsing limitations:** Regex-based pattern matching rather than
a full AST parser — complex SQL may not be detected. Acceptable for an
initial gate.
- **Low risk to existing behavior:** The gate only fails on *new*
findings not present in the baseline. All existing migrations are
baselined.
## Model Used
- **Provider:** Anthropic
- **Model ID:** `claude-sonnet-4-6`
- **Context window:** 200K
- **Tool use:** yes (file reading, bash, git operations)
- **Reasoning mode:** standard (no extended thinking)
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Summary
Local OpenClaw gateways since v2026.5.x require
`MIN_CLIENT_PROTOCOL_VERSION = 4` (see
[openclaw/src/gateway/protocol/version.ts](https://github.com/NousResearch/openclaw/blob/main/src/gateway/protocol/version.ts)).
The Paperclip openclaw_gateway adapter at v0.3.1 still sends
`PROTOCOL_VERSION = 3`, which produces a WebSocket close (code 1002
\`protocol mismatch\`) before any auth challenge is issued.
## Symptom
Every \`openclaw_gateway\` agent run fails with:
- \`errorCode: openclaw_gateway_request_failed\`
- \`error: protocol mismatch\`
OpenClaw gateway journal:
\`\`\`
[ws] protocol mismatch conn=... remote=127.0.0.1 client=gateway-client
backend vpaperclip
[ws] closed before connect conn=... peer=...->127.0.0.1:18789 code=1002
reason=protocol mismatch
\`\`\`
## Fix
One-line bump in
[\`packages/adapters/openclaw-gateway/src/server/execute.ts:89\`](packages/adapters/openclaw-gateway/src/server/execute.ts#L89):
\`PROTOCOL_VERSION = 3\` → \`PROTOCOL_VERSION = 4\`. No protocol
semantics changed — the adapter's existing frames are compatible with
v4.
## Test plan
- [x] \`pnpm --filter @paperclipai/adapter-openclaw-gateway typecheck\`
clean
- [x] \`pnpm --filter @paperclipai/adapter-openclaw-gateway build\`
clean
- [x] Verified locally: openclaw_gateway agent connects + receives
challenge + completes auth handshake after the bump
## Related
- Same root cause affects every openclaw_gateway-backed agent in the
field. Sparkeros companies SparkEros, Inc. and SparkEros AOS Inc. both
hit it.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agent work can run in shared, isolated, or operator-branch execution
workspaces
> - Isolated/operator git-worktree modes require a real git checkout as
their base
> - A projectless issue can otherwise resolve to the agent fallback
workspace directory
> - That fallback is not a valid project checkout for git worktree setup
> - This pull request adds a setup-time guard before workspace
realization starts
> - The benefit is that misconfigured work fails with a typed
remediation instead of raw git errors or accidental execution from the
agent home directory
## Linked Issues or Issue Description
No public GitHub issue was found for this specific failure mode. Inline
description follows the bug report template:
**What happened?**
When a Paperclip issue has no associated project (`projectId: null`) and
is configured for `isolated_workspace` or operator-branch execution with
`strategy: git_worktree`, the heartbeat setup silently fell back to the
`agent_home` directory as the base workspace. Because `agent_home` is
not a git repository checkout, the subsequent git worktree operations
either failed with raw git errors or — in the degraded path — ran in the
wrong directory entirely.
**Expected behavior**
A projectless issue requesting `git_worktree` execution should fail
immediately at setup with a typed `workspace_validation_failed` result
and a human-readable remediation message explaining that a project
workspace or a reusable execution workspace with a valid git base is
required.
**Steps to reproduce**
1. Create a Paperclip issue with `projectId: null` (no project
attached).
2. Assign it to an agent configured for `isolated_workspace` execution
with `strategy: git_worktree`.
3. Trigger a heartbeat run.
4. Observe: the heartbeat resolves the base workspace to `agent_home`
and either emits raw git errors during worktree setup or silently
executes from an incorrect directory.
**Paperclip version or commit**
`5cdf5103c` (current `master` HEAD at time of fix)
**Deployment mode**
Local dev (`pnpm dev`) / built from source — reproduces in any mode
because the fallback is in core workspace resolution logic.
**Agent adapter(s) involved**
Not adapter-specific (core bug — affects all adapters that issue
heartbeats for projectless tasks)
**Database mode**
Not database-related
**Access context**
Agent (bearer API key via `agent_api_keys`)
## What Changed
- Added a heartbeat setup guard that validates isolated/operator
`git_worktree` base workspaces before realization.
- The guard fails projectless `agent_home` fallback cases with a typed
`workspace_validation_failed` result and remediation text.
- The guard also fails non-git project base directories before raw git
worktree operations run.
- Added regression coverage for projectless isolated mode,
operator-branch mode, non-git bases, valid git bases, and
shared-workspace no-op behavior.
## Verification
- `pnpm exec vitest run
server/src/__tests__/heartbeat-workspace-session.test.ts`
- `pnpm exec vitest run server/src/__tests__/workspace-runtime.test.ts`
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm -r typecheck`
- `pnpm test:run`
- `pnpm build`
## Risks
- Low risk. The new guard only applies to issue-backed isolated/operator
execution modes using `git_worktree`; shared workspaces and
non-git-worktree strategies are left unchanged.
- The intentional behavior shift is that invalid git-worktree bases now
fail earlier with a structured remediation instead of reaching
lower-level git setup.
## Model Used
- OpenAI GPT-5 Codex, coding-agent tool-use mode with local command
execution; context window size not exposed by this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip stores agent work in a PostgreSQL database that evolves
via numbered sequential migrations
> - Migrations that run large unbounded table scans can block the
server's `listen()` call during upgrades, causing multi-minute startup
stalls on large databases
> - Migration 0126 ran a full sequential scan backfill over
`issue_comments` for derived attribution columns — O(n²) due to
unindexed `LIMIT`/`OFFSET` batching, pegging CPU for ~5 minutes on a 3–4
M row table
> - The safe fix (landed in #9108) replaced 0126 with a new forward-only
migration using a partial index + keyset pagination backfill
> - But the root cause is the absence of author-time guidance:
contributors have no documented rules for writing bounded, indexed
migration backfills before they land
> - This PR adds a migration authoring checklist to `doc/DATABASE.md` so
future contributors have those rules at hand before opening a PR
> - The benefit is a durable, discoverable guide that prevents the same
class of startup-blocking slowness before it reaches production
## Linked Issues or Issue Description
This PR is a documentation follow-on to #9108, which landed the fast
0132 migration fix. It adds author-time guidance that captures the
root-cause lesson from that incident.
No separate public issue exists for the doc addition; the motivation is
described above.
Refs #9108
## What Changed
- `doc/DATABASE.md`: Added a **Migration authoring checklist** section
with rules for indexed, bounded backfill batches — keyset pagination
over `LIMIT`/`OFFSET`, mandatory partial index, idempotent guards, and
split-phase schema-vs-data changes. The `check:migrations` CI gate is
referenced as the enforcement backstop.
## Verification
- `git diff --check -- doc/DATABASE.md` passes (no whitespace errors).
- No executable code changed; the checklist is an additive documentation
section.
## Risks
Low. The change is additive text in `doc/DATABASE.md`. No schema,
migration, or code changes. No behavioral diff.
## Model Used
Claude claude-sonnet-4-6 (Anthropic, 200 K context, tool use) — used to
author the migration authoring checklist and coordinate the PR workflow.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with \`Fixes: #\` /
\`Closes #\` / \`Refs #\` OR (b) described the issue in-PR following the
relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub \`#NNN\` /
\`github.com/paperclipai/paperclip\` URLs)
- [x] My branch name describes the change (e.g. \`docs/...\`,
\`fix/...\`) and contains no internal Paperclip ticket id or
instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents run in git worktrees tied to a workspace branch; when the
actual branch diverges from the expected one (e.g. a parent feature
branch was renamed), Paperclip currently has no structured field to
report *why* the branch is incoherent or whether it can be
auto-reconciled
> - The workspace-incoherence fingerprint already captures SHA
mismatches, but there is no evidence field distinguishing "actual branch
is a descendant of expected" (safe to fast-forward) from "branches have
diverged" (needs human review) or "SHAs are unavailable" (unknown)
> - Operators and future recovery flows need a typed verdict to make
decisions without re-running git commands themselves
> - This pull request adds `ancestryVerdict` and `plainLanguageReason`
evidence fields computed via `git merge-base --is-ancestor`, and
scaffolds the off-by-default `enableWorkspaceBranchReconcileForward`
instance setting with no runtime behavior yet
> - The benefit is that future recovery logic can branch on a typed
verdict rather than parsing prose, while the fingerprint v1 payload
stays stable
## Linked Issues or Issue Description
No public GitHub issue pre-exists for this diagnostic addition.
**Problem or motivation**
When Paperclip detects that an agent's actual workspace branch differs
from the recorded expected branch, the current fingerprint carries only
raw SHAs. There is no typed field indicating whether the actual branch
is a descendant of the expected one (safe reconcile path) vs. a true
divergence (requires human intervention) vs. an indeterminate state
(missing SHAs or git errors). Downstream recovery logic cannot branch
safely without re-running git.
**Proposed solution**
Add `ancestryVerdict` and `plainLanguageReason` to the workspace
incoherence evidence type; compute via `git merge-base --is-ancestor`;
scaffold a feature-flag for future forward-reconcile behavior
(`enableWorkspaceBranchReconcileForward`, off by default, not yet read
by any runtime path).
**Alternatives considered**
Encoding the verdict in the existing fingerprint string was rejected
because the fingerprint is a stable identity hash, not a mutable
evidence bag. Changing it would break monitors keyed on the string.
**Roadmap alignment**
Supports future workspace auto-reconcile work; ROADMAP.md has no
conflicting entry for this diagnostic layer.
## What Changed
- `packages/shared/src/types/heartbeat.ts` adds `ancestryVerdict` and
`plainLanguageReason` fields to `WorkspaceIncoherenceEvidence`
- `packages/shared/src/types/instance.ts` adds
`enableWorkspaceBranchReconcileForward` boolean (off by default)
- `packages/shared/src/validators/instance.ts` exports the new flag from
the settings validator
- `server/src/services/workspace-runtime.ts` computes `ancestryVerdict`
via `git merge-base --is-ancestor`; falls back to `unknown` on missing
SHAs or command errors; excludes verdict fields from fingerprint v1
computation
- `server/src/services/instance-settings.ts` wires the new setting
through to the settings service
- Tests updated in `workspace-runtime.test.ts`,
`instance-settings-service.test.ts`, `instance-settings-routes.test.ts`,
and `instance.test.ts` (104 tests total)
## Verification
```bash
pnpm exec vitest run \
server/src/__tests__/workspace-runtime.test.ts \
server/src/__tests__/instance-settings-service.test.ts \
server/src/__tests__/instance-settings-routes.test.ts \
packages/shared/src/validators/instance.test.ts
# 104 tests pass
pnpm --filter @paperclipai/shared typecheck
pnpm --filter @paperclipai/server typecheck
# both exit 0
```
Manual: trigger a workspace incoherence event and confirm the evidence
object carries `ancestryVerdict` and `plainLanguageReason`; confirm the
fingerprint string stays `workspace_incoherence:v1:sha256:...`.
## Risks
**Low risk.** Purely additive. Fingerprint v1 payload is unchanged. The
new flag has no runtime effect in this PR. `git merge-base
--is-ancestor` exits non-zero for both "not an ancestor" and "command
error"; both are handled and collapsed to typed values with a prose
reason.
## Model Used
Provider: Anthropic, model: Claude Sonnet 4.6 (`claude-sonnet-4-6`),
200k context, tool use enabled.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Problem
On the Agents page, there are two small icon buttons for switching
between list view and org chart view. But these buttons had:
- No title attribute, so hovering show nothing
- No aria-label, so screen readers just say "button"
- No aria-pressed, so no way to know which view is active
- No role="group" on the container
I was confused the first time I see these buttons because one is a list
icon and the other is a git-branch icon, and without hovering or
clicking I had no idea what they do. Specially the git-branch icon - is
it for branches? Repos? No, it's for org chart view.
## What I changed
- Added `title` to each button: "List view" and "Org chart view"
- Added `aria-label` matching the title for screen readers
- Added `aria-pressed` to indicate which view is currently selected
- Added `role="group"` with `aria-label="View mode"` on the container
div
## How to test
1. Go to Agents page (must have more than 1 agent for toggle to appear)
2. Hover over the list icon - should see "List view" tooltip
3. Hover over the branch icon - should see "Org chart view" tooltip
4. Use screen reader - should announce "List view, pressed" or "Org
chart view, not pressed"
1 file, 7 lines added.
## Thinking Path
> - `doc/SPEC-implementation.md` §5.2 (Out of Scope V1) conflates two
distinct concerns into a single bullet: _"Multi-board governance or
role-based human permission granularity"_.
> - Role-based human permission granularity has been V1 for a while —
the `humans-and-permissions` plan and the `principal_permission_grants`
table shipped, the `PERMISSION_KEYS` set covers `users:invite`,
`users:manage_permissions`, `tasks:assign`, `tasks:assign_scope`,
`tasks:manage_active_checkouts`, `tasks:view_all`, `agents:view_all`,
`joins:approve`, `agents:create`, `environments:manage`.
> - The remaining OOS item from that bullet is _multi-board governance_
— running multiple board UIs against one company. That's a
deployment-topology concern, separate from permission granularity, and
stays V1 OOS.
> - This PR splits the bullet so the OOS list reflects reality and
contributors don't read the SPEC and conclude that per-user permission
scoping is unplanned.
## What Changed
Single-file docs edit in `doc/SPEC-implementation.md` §5.2:
- Drop the conflated "Multi-board governance or role-based human
permission granularity" bullet.
- Keep "Multi-board governance (multiple board UIs for a single
company)" as OOS — that part is still out of scope.
- Add a short paragraph below the OOS list pointing readers to the
`humans-and-permissions` plan, `principal_permission_grants`, and the
existing `tasks:view_all` + `agents:view_all` opt-out scoping primitives
so anyone reading §5.2 finds the V1 surface immediately.
## Verification
- N/A — docs-only change, no code/schema/test impact.
## Risks
- None. Single bullet rewording.
## Model Used
Claude (Anthropic). Model ID: `claude-opus-4-7`.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work — it documents already-shipped V1 work that the SPEC
was lagging on
- [x] I have run tests locally and they pass — N/A docs-only
- [x] I have added or updated tests where applicable — N/A
- [x] If this change affects the UI, I have included before/after
screenshots — N/A docs-only
- [x] I have updated relevant documentation to reflect my changes — this
PR IS the doc update
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Mike <ms@moar.tools>
Co-authored-by: Andrew Aymeloglu <aaymeloglu@gmail.com>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Users triage agent work through the issue inbox, which suppresses
archived issues by comparing issue `updated_at` against the archive
timestamp
> - Migration `0130_run_responsible_user_invariant` backfilled
responsible-user columns but also set `updated_at = now()` on every row
it touched (companies, issues, routines, routine_runs, heartbeat_runs)
> - That blanket timestamp bump made every archived issue look newly
updated, resurfacing thousands of archived issues into every user's
inbox
> - This pull request corrects the 0130 backfill in place so it only
fills `NULL` responsible-user columns and never touches timestamps, and
adds tests that prevent this class of bug from being reintroduced
> - The benefit is that inbox archive suppression stays intact across
migrations, and no future migration backfill can silently bump
`updated_at` on user-visible tables
## Linked Issues or Issue Description
**Bug description (no public issue exists):**
- **What happened:** after upgrading a dev instance across migration
0130, every previously archived inbox item resurfaced as unread/new for
all users.
- **Expected:** data backfills must not alter row modification
timestamps; archived issues stay archived unless genuinely updated.
- **Root cause:** the 0130 backfill's `UPDATE` statements set
`updated_at = now()` alongside the responsible-user columns.
## What Changed
- `packages/db/src/migrations/0130_run_responsible_user_invariant.sql`:
removed all `updated_at = now()` assignments from the backfill UPDATEs;
the migration now only fills `NULL` responsible-user columns. The file
is corrected **in place** (no new migration number, journal untouched)
because 0130 has never shipped in a published release.
- `packages/db/src/client.test.ts`: added a guard test that scans every
migration and rejects backfills that bump `updated_at` on user-visible
tables (with an explicit allowlist for the pre-existing 0131 repair
migration).
- `packages/db/src/client.test.ts`: added a replay test that simulates
an already-migrated database picking up the corrected file (deletes the
0130 ledger hash, re-applies mid-journal) and asserts issue `updated_at`
and inbox-archive suppression ordering are untouched.
### Why an in-place edit is safe
- 0130 only exists on master/canary builds; the latest published release
(v2026.626.0) predates it.
- The migration ledger is content-hash based: databases that already
applied the old 0130 keep an orphaned hash row (harmless) and see the
corrected file as pending, so they replay the corrected backfill — which
is idempotent (fills `NULL`s only, no timestamp writes).
- Fresh databases simply run the corrected 0130 in journal order.
## Verification
- `pnpm --filter @paperclipai/db run check:migrations` — clean
- `cd packages/db && npx vitest run src/client.test.ts` — 11/11 passing
against embedded Postgres, including the new guard and mid-journal
replay tests
## Risks
- Migration safety: the corrected backfill is idempotent and only writes
`NULL` columns; replay on already-migrated databases is exercised
directly by the new test. No schema changes.
- Databases that already ran the old 0130 keep the bumped timestamps
from that run; repairing historical damage is intentionally out of scope
here (no released build ever contained the bug).
## Model Used
- Claude Opus 4.7 (`claude-opus-4-7`, extended thinking, tool use) via
Claude Code / Paperclip agent runtime
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above (backup health alert work split into #9113; no other related
open PRs)
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes (none
needed for a migration content fix)
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The board UI is where operators create issues, inspect issue-thread
decisions, write markdown, and move between issue workflow surfaces.
> - A broad recovered branch mixed these operator workflow polish fixes
with unrelated backend, pipeline, plugin, eval, and work-product
changes.
> - Reviewers need the operator UI workflow fixes in a small PR that can
be understood without pulling in the rest of that recovery branch.
> - This pull request extracts only the issue workflow UI slice:
interaction cards, markdown editing fallback behavior, create-issue work
mode shortcuts, file-viewer URL handling, and issue navigation scroll
behavior.
> - The benefit is a lower-risk review path for operator workflow fixes
while keeping unrelated execution-workspace and server work out of this
PR.
## Linked Issues or Issue Description
- Refs #8866, the closed broad source PR that this focused slice was
extracted from.
- Related: #8228 is an open UI polish PR, but its file list does not
overlap this branch.
- Related: #4090 is older merged operator workflow polish context.
No public GitHub issue exists for this exact extracted slice. The
problem is that several small operator issue-workflow fixes were bundled
inside a broad recovery branch, making them hard to review and ship
independently.
## What Changed
- Removed interaction continuation wake-policy labels from issue-thread
interaction card headers and updated the card test/story copy
accordingly.
- Added a markdown editor error boundary so rich editor render crashes
fall back to a raw textarea instead of breaking the compose surface.
- Made the create-issue work-mode shortcut accept ctrl-period and iOS
hardware-keyboard command-period-as-Escape behavior without dismissing
the dialog.
- Fixed file-viewer URL navigation to compare against the live browser
search string when router state is stale.
- Restored scroll reset when navigating from an issue detail route back
to the issue index, while preserving browser-history restoration
behavior.
## Screenshots
Before removing the continuation wake-policy badge from interaction card
headers:
After removing the wake-policy badge:
## Verification
- `pnpm exec vitest run
ui/src/components/IssueThreadInteractionCard.test.tsx
ui/src/components/MarkdownEditor.test.tsx
ui/src/components/NewIssueDialog.test.tsx
ui/src/context/FileViewerContext.test.ts
ui/src/lib/navigation-scroll.test.ts` — 5 files, 102 tests passed.
- `pnpm --filter @paperclipai/ui typecheck` — passed.
- `git diff --check` — passed.
## Risks
Low risk. The PR is limited to UI workflow components/helpers and their
tests. Main behavioral risks are keyboard shortcut edge cases across
browsers and fallback editor rendering, both covered by focused tests.
## Model Used
OpenAI Codex, GPT-5-based coding agent (`gpt-5` family; exact served
variant and context window are not exposed in this runtime), with
terminal, Git, GitHub, and test execution tools.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source control plane people use to manage AI
agents for work.
> - Backend execution safety is part of the control plane contract:
agents must stop at budget hard limits, stale execution paths must not
create duplicate live work, and checkout ownership must remain
authoritative.
> - The recovery branch bundled these release-gate checks with broader
unrelated work.
> - Reviewers need a narrow PR that isolates only the backend safety
behavior and regression coverage.
> - This pull request keeps budget incident creation idempotent so
repeated evaluation does not duplicate release-gate telemetry or
approvals.
> - It also adds focused coverage for idle timer skips, stale queued-run
behavior, and live checkout conflict preservation.
> - The benefit is a smaller, reviewable release-gate slice for budget
hard stops, stale execution recovery, and ownership-safe issue mutation.
## Linked Issues or Issue Description
Refs #8866
This PR extracts a focused backend safety slice from the closed broad
recovery PR. The underlying problem is that release-gate behavior needs
direct regression coverage before review: budget hard stops should not
duplicate incidents/logging on repeated evaluation, timer wakes should
respect the no-actionable-work skip policy, stale queued runs should
remain invalidated, and active checkout ownership must survive
conflicting checkout attempts without side effects.
## What Changed
- Made budget incident creation report whether an incident was newly
created, so soft/hard threshold activity logs are emitted once per
incident window.
- Added embedded Postgres budget release-gate tests covering soft
incident idempotency, hard-stop pause/cancel behavior, budget override
resume behavior, and telemetry redaction.
- Added heartbeat coverage for skipping generic timer wakes when the
agent opts into `skipTimerWhenNoActionableWork`, while preserving
legacy/proactive timer behavior.
- Added stale execution lock route coverage proving a conflicting
checkout returns `409` without overwriting live checkout or execution
ownership and without writing checkout activity.
## Verification
- `./node_modules/.bin/vitest run
server/src/__tests__/budgets-service.test.ts
server/src/__tests__/heartbeat-process-recovery.test.ts
server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts
server/src/__tests__/issue-stale-execution-lock-routes.test.ts
--no-file-parallelism --maxWorkers=1`
- First run: 3 files passed, 98 tests passed;
`issue-stale-execution-lock-routes.test.ts` failed during import because
the isolated worktree initially lacked dev dependency links for
`supertest`.
- `CI=true NODE_ENV=development pnpm install --frozen-lockfile
--ignore-scripts`
- Recreated worktree dev dependency links; emitted unrelated plugin SDK
bin warnings because plugin SDK dist files were not built under
`--ignore-scripts`.
- `./node_modules/.bin/vitest run
server/src/__tests__/issue-stale-execution-lock-routes.test.ts
--no-file-parallelism --maxWorkers=1`
- Passed: 1 file, 7 tests.
- `git diff --check`
- Passed.
## Risks
Low to medium risk. The production code change is intentionally small
and only suppresses duplicate threshold activity logging for
already-open budget incidents, but it affects budget release-gate
observability. The new tests use embedded Postgres and should catch
regressions in budget hard stops, timer wake gating, stale queue
invalidation, and checkout conflict preservation.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5 coding agent, tool-use enabled.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source control plane people use to manage AI
agents for work.
> - The relevant subsystem is the agent heartbeat policy surface: the
Paperclip skill, default onboarding AGENTS.md, new-agent runtime
defaults, and promptfoo eval coverage for agent behavior.
> - A broad recovery PR collected several unrelated local-mainline
changes, which made review too large and mixed policy/eval updates with
server execution and UI work.
> - This PR extracts only the heartbeat policy and prompt-eval slice so
reviewers can assess the behavior contract independently.
> - The eval additions cover scoped wake handling, idle no-op behavior,
dependency-blocked comment triage, final disposition, budget hard stops,
and Phase 5 memory/control-surface policy expectations.
> - The benefit is a narrower review surface plus deterministic
follow-up guidance for server/shared tests that should back these
prompt-level checks.
## Linked Issues or Issue Description
Refs #8866
No public issue was filed for this split. This is a focused extraction
from the closed broad recovery PR so heartbeat policy and eval coverage
can be reviewed separately from execution behavior, work-product feature
work, plugin hardening, pipeline health, and unrelated UI polish.
## What Changed
- Added promptfoo release-gate cases for scoped wake payload handling,
idle exits, dependency-blocked comment triage, final disposition, and
budget hard-stop behavior.
- Added Phase 5 memory/control-surface prompt eval cases for provider
binding precedence, provenance/audit fields, hook cost/trust handling,
and auditable board command surfaces.
- Documented how these prompt evals map to deterministic server/shared
follow-up coverage.
- Updated agent policy guidance so operator-facing engineering outputs
such as PRs, branches, commits, previews, and runtime services get
matching work products.
- Defaulted new agent runtime config to skip timer heartbeats when there
is no actionable work, with focused test coverage.
## Verification
- `cd evals/promptfoo && npx promptfoo@latest validate -c
promptfooconfig.yaml` passes.
- `/srv/paperclip/home/paperclipai/paperclip/node_modules/.bin/vitest
run ui/src/lib/new-agent-runtime-config.test.ts` passes in an isolated
worktree after `pnpm install --ignore-scripts --frozen-lockfile` created
workspace links.
- A live promptfoo eval was not run because `OPENROUTER_API_KEY`,
`OPENAI_API_KEY`, and `ANTHROPIC_API_KEY` were unset in the workspace.
## Risks
Low-to-medium risk. The runtime default reduces timer-driven empty
heartbeats for newly created agents, so the main behavioral risk is
missing an edge case where timer wakes were expected despite no
actionable work. The promptfoo additions are deterministic assertion
coverage and documentation-only until a live eval is run with provider
credentials.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI GPT-5-based Codex coding agent in the Paperclip local Codex
adapter environment; exact hosted model ID and context window were not
exposed to the agent runtime. Tool use included shell, git, promptfoo
validation, Vitest, and the GitHub connector/CLI.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The board UI is the main daily navigation surface for agents,
projects, and their related resources.
> - Operators need a lightweight way to keep frequently used agents and
projects close without changing company-wide ordering or ownership.
> - Resource memberships already model per-user relationships to
projects and agents, so they are the right place to store user-specific
starred state.
> - This pull request extends that membership contract with a starred
timestamp and exposes star controls in list/detail views.
> - The sidebar then uses those starred memberships to show compact,
user-specific shortcuts.
> - The benefit is faster navigation without introducing a separate
favorites system or leaking preferences across users.
## Linked Issues or Issue Description
No public GitHub issue exists.
Feature request:
## Problem or motivation
Users cannot pin frequently used agents or projects into the main
sidebar. Returning to important resources requires scanning full
project/agent lists or navigating through detail pages, which adds
friction to repeated daily workflows.
## Proposed solution
Store a per-user `starred_at` timestamp on agent and project
memberships, expose API actions to set or clear that state, add star
toggle controls to list/detail pages, and render starred projects and
agents as compact sidebar shortcuts.
## Alternatives considered
A separate favorites table would work, but it would duplicate membership
scoping and require another resource relationship model. Keeping starred
state on memberships preserves existing company/user boundaries and
avoids a second source of truth.
## Roadmap alignment
Checked `ROADMAP.md`; no overlapping planned core work for starred
resource/sidebar navigation was found.
## Additional context
The affected subsystems are `packages/db`, `packages/shared`, `server/`,
and `ui/`. The migration is idempotent with `IF NOT EXISTS` guards so
environments that saw an earlier local migration name can still apply
the final ordered migration safely.
## What Changed
- Added idempotent migration `0133_resource_membership_stars` for
`starred_at` columns and lookup indexes on agent/project memberships.
- Extended shared resource membership types and validators with starred
metadata and actions.
- Updated server resource membership services/routes to read and mutate
starred resource state.
- Added reusable star toggle UI and resource membership hook support for
starred state.
- Added starred projects and agents sidebar rendering, plus star
controls on list and detail pages.
- Added focused shared, server, and UI coverage for starred membership
behavior and sidebar rendering.
## Verification
- Rebased and force-with-lease pushed current PR head
`a086fc965391c9e50a51b5b83b5b44a797b2a6f4` onto current
`paperclipai/paperclip:master`; `gh pr view` reports `MERGEABLE` with no
merge conflicts. GitHub checks are green for this fresh head.
- `pnpm exec vitest run packages/shared/src/resource-memberships.test.ts
server/src/__tests__/resource-memberships-routes.test.ts
server/src/__tests__/workspace-runtime.test.ts
ui/src/components/Sidebar.test.tsx
ui/src/components/SidebarAgents.test.tsx
ui/src/components/SidebarStarredProjects.test.tsx
ui/src/components/StarToggle.test.tsx
ui/src/pages/InstanceExperimentalSettings.test.tsx` passed after the
rebase: 8 files, 143 tests.
- Greptile re-review is 5/5; the remaining screenshot thread was
resolved as non-blocking because this task explicitly requested no
screenshots/images in the PR.
- `pnpm exec vitest run
ui/src/components/SidebarStarredProjects.test.tsx` passed after the
mobile pending-spinner fix.
- `pnpm exec vitest run packages/shared/src/resource-memberships.test.ts
server/src/__tests__/resource-memberships-routes.test.ts
ui/src/components/Sidebar.test.tsx
ui/src/components/SidebarAgents.test.tsx
ui/src/components/SidebarStarredProjects.test.tsx
ui/src/components/StarToggle.test.tsx
ui/src/pages/InstanceExperimentalSettings.test.tsx` passed: 7 files, 68
tests.
- `pnpm --filter @paperclipai/db typecheck && pnpm --filter
@paperclipai/shared typecheck && pnpm --filter @paperclipai/server
typecheck && pnpm --filter @paperclipai/ui typecheck` passed
db/shared/server, then failed in pre-existing UI code outside this PR:
`src/pages/CompanyEnvironments.tsx` missing `@xterm/*` type declarations
and `previous` possibly null.
- Checked that the PR diff does not include `pnpm-lock.yaml` or
`.github/workflows` changes.
- Checked `ROADMAP.md` and found no overlapping planned core work for
starred resource/sidebar navigation.
- Searched existing GitHub PRs for duplicate starred-resource/sidebar
work and found none.
## Risks
- Migration touches membership tables. The SQL uses `IF NOT EXISTS` for
columns and indexes so environments that saw an earlier local migration
name can still apply this safely.
- Sidebar ordering and visibility changes could affect users who rely on
the previous flat sidebar layout.
- Starred state is per-user membership metadata; code paths must
continue preserving company/user scoping around memberships.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI GPT-5 Codex, tool-enabled coding agent with shell/GitHub access.
Context window not disclosed by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Hermes adapter produces terminal output with ANSI color codes on
stdout
> - These escape sequences flow through the UI parsers untouched and
render as raw garbage text
> - This PR adds ANSI stripping at the entry point of all four Hermes
parse-stdout entry points
> - The same regex is already proven in claude-local adapter
> - The benefit is clean, readable terminal output for Hermes agents
## Linked Issues or Issue Description
No existing issue. This is a bug report:
**What happened**
Hermes terminal output displayed ANSI color codes as raw text in the
Paperclip UI, making agent output unreadable.
**Expected behavior**
Terminal output in run transcripts should be clean text without
invisible control characters.
**Steps to reproduce**
1. Connect a Hermes agent to Paperclip
2. Create and assign a task to the agent
3. View the run transcript — ANSI escape codes appear as raw garbage
**Paperclip version or commit**
e6407b322 (upstream master)
**Deployment mode**
local_trusted
## What Changed
- Added `stripAnsi()` function using the same regex pattern from
claude-local adapter (quota.ts) — strips CSI and
OSC sequences
- Applied at entry point of `parseHermesStdoutLine` in hermes_local (TS
+ CJS)
- Applied at entry point of `parseHermesGatewayStdoutLine` in
hermes_gateway (TS + CJS)
- CJS files keep the function inline since the dynamic parser sandbox
has no module loader
- 5 files changed, +123/-8 lines
## Verification
- Smoke tested with real ANSI patterns from Hermes output — all samples
pass
- `pnpm --filter @paperclipai/hermes-paperclip-adapter exec vitest run
src/ui/parse-stdout.test.ts` — 9 passed
- TypeScript compiles clean for both hermes and hermes-gateway packages
- Adapter tests pass (5/6, 1 pre-existing Windows CI failure unrelated)
- Live tested on running Paperclip instance — ANSI codes no longer
appear in transcripts
## Risks
Low risk. Only affects Hermes parser output. Regex already proven in
claude-local adapter. No logic changes to parse
behavior — only strips invisible control characters before parsing.
## Model Used
DeepSeek V4 Pro — reasoning mode, tool use
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue
in-PR following the relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` /
`github.com/paperclipai/paperclip` URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id
or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The database layer runs migrations during server startup via
`server.listen`; migrations that block this path delay instance
availability
> - Migration `0126_issue_comment_derived_attribution.sql` backfills
derived attribution columns on `issue_comments` using a LIMIT-5000 loop
with no index or keyset cursor — it re-scans the full table from the
start each batch, giving O(n²) complexity
> - On instances with millions of issue comments this blocked
`server.listen` for ~5 minutes during upgrade, causing CPU pegs and
unavailability
> - Editing 0126 in place is unsafe: the migration runner keys its
applied-set on file **content hash**, so any edit changes the hash,
causing the runner to re-apply the migration on already-migrated
databases and blocking startup
> - The safe remedy is delete-and-relocate: remove 0126 and add a new
forward migration 0132 that uses a temporary partial index + keyset
pagination (`id > last_comment_id ORDER BY id LIMIT 5000`) so every row
is visited exactly once — O(n)
> - This pull request implements that delete-and-relocate with
idempotency guards (IF NOT EXISTS DDL, backfill WHERE clause that skips
already-attributed rows) so it is a safe near-noop on already-migrated,
partially-migrated, and fresh databases alike
## Linked Issues or Issue Description
No pre-existing public GitHub issue. Inline bug report:
**What happened?**
The `0126_issue_comment_derived_attribution` migration runs during
server startup and uses a LIMIT-5000 batch loop that re-scans
`issue_comments` from row 1 each iteration (no index, no keyset cursor).
The result is O(n²) I/O that blocked `server.listen` on large instances.
**Expected behavior**
Backfill migrations should advance with a keyset cursor so each batch
reads a new slice; total work is O(n) and startup is not blocked.
**Steps to reproduce**
Run a Paperclip upgrade on an instance with ≥200k issue comments;
observe `server.listen` blocked for several minutes and CPU peg during
migration.
**Paperclip version or commit**
Reproduced on the current `master` branch prior to this fix.
**Deployment mode**
All deployment modes that run the migration runner at startup.
## What Changed
- **Deleted**
`packages/db/src/migrations/0126_issue_comment_derived_attribution.sql`
— the O(n²) LIMIT-5000 loop with no index/cursor
- **Added**
`packages/db/src/migrations/0132_issue_comment_derived_attribution_fast.sql`:
- Creates a temporary partial index over the eligible predicate before
backfilling
- Uses keyset pagination (`id > last_comment_id ORDER BY id LIMIT 5000`)
— each batch advances to the batch-max id, so every row is visited once
- Drops the temporary index at the end
- Columns/FKs guarded with `IF NOT EXISTS`; Option-A timing-tier cleanup
preserved; human-authored comments never touched
- `WHERE` clause in the backfill excludes rows already attributed (safe
near-noop on already-migrated DBs)
- **Updated** `packages/db/src/migrations/meta/_journal.json` — dropped
0126 entry, appended 0132
- **Added**
`packages/db/src/issue-comment-derived-attribution-migration.test.ts`
(345 lines) — covers fresh-install, already-0126-migrated idempotency,
and partial-backfill completion scenarios using embedded Postgres
## Verification
```bash
# Migration numbering guard
pnpm --filter @paperclipai/db check:migrations
# Migration tests (embedded Postgres, 3 scenarios)
pnpm --filter @paperclipai/db vitest run issue-comment-derived-attribution-migration.test.ts
```
Both pass locally. CI results will appear on this PR.
## Risks
**Migration safety — already-migrated databases:** Deleting 0126 leaves
an orphan row in the runner's applied-set. The runner only checks the
set for "has this been applied" — orphan rows are never re-applied. 0132
runs as a near-noop: IF NOT EXISTS DDL is skipped, and the backfill
WHERE clause excludes rows that already have attribution.
**Migration safety — partially-migrated databases:** Keyset pagination
is idempotent. 0132 picks up from the highest attributed row id, so a
partial prior run is completed correctly.
**No data loss:** The migration never deletes or overwrites
user-authored content. It only writes to derived attribution columns on
rows where attribution is absent.
**Rollback:** 0132 is a forward-only migration. If a rollback is needed,
the attribution columns remain (no harm) and can be ignored or cleaned
up in a subsequent migration.
## Model Used
Claude Sonnet 4.6 (`claude-sonnet-4-6`) via the Paperclip AI agent
harness, with tool use and extended context enabled. Implementation
authored by Priya Raman; PR opened via the Paperclip Git Expert agent.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [ ] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
_(branch is the preserved implementation branch from the authoring
engineer; the internal task id is present in the branch name by workflow
convention — not a content risk)_
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green _(pending — CI running)_
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
_(pending — will be driven to terminal-green before merge)_
- [ ] I will address all Greptile and reviewer comments before
requesting merge _(pending — will action all findings)_
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip stores heartbeat run ownership context so operators can
audit which user was responsible for agent work
> - A migration backfills missing heartbeat run `responsible_user_id`
values from issue references in each run's context snapshot
> - Some context snapshots can store issue identifiers as public ticket
strings rather than UUIDs
> - The migration needs to resolve both UUID issue ids and issue
identifiers without trying to cast identifier strings to UUID
> - This pull request tightens the migration query so UUID matching only
casts validated UUID-shaped values and identifier matching remains a
separate fallback
> - A companion repair migration is needed so installations that already
recorded `0130` still get the corrected heartbeat-run backfill
> - The benefit is that existing installations can apply the
responsible-user invariant migrations without failing on non-UUID issue
references and without leaving already-migrated databases unrepaired
## Linked Issues or Issue Description
No public GitHub issue was found in a quick search for this migration
failure.
Bug report context following `.github/ISSUE_TEMPLATE/bug_report.yml`:
**Pre-submission checklist**
- I searched existing open and closed issues and did not find a
duplicate.
- I can reproduce against current `master` plus the responsible-user
invariant migration path.
- The error originates in Paperclip's database migration, not in an
adapter, API provider, or local configuration.
**What happened?**
Applying the heartbeat run responsible-user backfill migration could
fail when `heartbeat_runs.context_snapshot->>'issueId'` or `taskId`
contained an issue identifier such as `PAP-123` instead of a UUID. The
migration attempted to use issue refs for UUID matching and identifier
fallback, but the UUID path needed to avoid casting non-UUID identifier
strings. Because `0130` may already have been applied in some
installations, a follow-up repair migration is needed as well.
**Expected behavior**
The migration should backfill from UUID issue ids when present, from
issue identifiers when present, and fall back to the company default
responsible user without unsafe UUID casts. Already-migrated
installations should receive the repaired heartbeat-run context-ref
backfill through a new migration.
**Steps to reproduce**
1. Use a migrated database with a company, issue, agent, and heartbeat
run.
2. Store a null `heartbeat_runs.responsible_user_id` and a
`context_snapshot` like `{"issueId":"PAP-123"}`.
3. Replay/apply the run responsible-user repair migration.
4. Observe that the migration must not cast `PAP-123` to UUID and should
backfill from the matching issue identifier.
**Paperclip version or commit**
Current `master` plus this migration fix branch.
**Deployment mode**
Database migration during server startup or explicit migration command.
**Installation method**
Built from source / self-hosted migration path.
**Agent adapter(s) involved**
Not adapter-specific; core database migration bug.
**Database mode**
Postgres migration path, including embedded Postgres in development.
**Access context**
Not applicable; migration-time data backfill.
**Relevant logs or output**
Unsafe UUID casts can surface as Postgres invalid input syntax errors
when a context snapshot issue ref is an identifier rather than a UUID.
**Privacy checklist**
No private logs, paths, API keys, tokens, company names, or internal
Paperclip issue links are included.
## What Changed
- Split heartbeat run context issue reference extraction into reusable
CTEs.
- Only cast `issueId` / `taskId` values to UUID after a UUID-shape regex
check.
- Preserve fallback matching by issue identifier within the same
company.
- Keep deterministic candidate priority with `issueId` before `taskId`
and UUID matches before identifier matches.
- Added `0131_repair_run_responsible_user_context_refs.sql` so
installations that already applied `0130` still receive the corrected
heartbeat-run backfill.
- Added a DB migration regression test that replays the repair migration
with an identifier-style heartbeat run issue ref.
## Verification
- `pnpm --filter @paperclipai/db typecheck`
- `pnpm --filter @paperclipai/db exec vitest run src/client.test.ts`
- Isolated embedded Postgres migration run with a temporary
`PAPERCLIP_CONFIG`: `pnpm --filter @paperclipai/db migrate` applied all
pending migrations successfully.
- GitHub Actions PR workflow is green on commit
`1c2655bc457cef3716a43e66463e1e5bc2fdcfab`.
- Greptile is 5/5 with no unresolved threads on commit
`1c2655bc457cef3716a43e66463e1e5bc2fdcfab`.
- Searched for duplicate public issues/PRs with GitHub search; no direct
duplicate found.
- Checked `ROADMAP.md` for overlap; no related roadmap item found.
## Risks
- Low-to-medium migration risk because this modifies an existing data
backfill migration and adds a companion repair migration.
- The query still relies on `context_snapshot` containing either issue
UUIDs or identifiers that match issues in the same company.
- Installations with unusual malformed context snapshots now skip unsafe
UUID casts and fall through to identifier/default backfill behavior.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI GPT-5 Codex coding agent with tool use and local command
execution.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes, or
confirmed no docs update is needed for this migration-only fix
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Pipeline health reports give operators early warnings when a
workflow step cannot run cleanly.
> - Failed stage automation is surfaced as an `automation_failed` health
warning for the affected item.
> - A single item can have repeated failed automation rows for the same
stage, especially after retries or repeated failed attempts.
> - Rendering every matching row creates duplicate warnings that make
the pipeline look noisier than it is.
> - This pull request deduplicates failed automation warnings by the
item/stage pair before adding them to the health report.
> - The benefit is that repeated failures for the same item in the same
stage produce one actionable warning, while distinct items still remain
visible.
## Linked Issues or Issue Description
Refs #8866
Bug: pipeline health could emit duplicate `automation_failed` warnings
when the input contained repeated failed automation rows for the same
live item and stage. Reviewers should expect one warning per
`stageId:caseId` pair, not one warning per backing execution row.
## What Changed
- Deduplicated failed automation warnings with per-stage case tracking
in `computePipelineHealth`, avoiding collision-prone composite string
keys before pushing `automation_failed` warnings.
- Added shared Vitest coverage for a single automation failure,
duplicate same-stage same-item dedupe, separate warnings for different
item IDs in the same stage, the same item ID in different stages, and
colon-delimited ID collision cases.
- Kept pipeline route behavior unchanged; this PR only changes shared
warning rendering and direct shared tests.
## Verification
- `pnpm vitest packages/shared/src/pipeline-health.test.ts`
- 1 test file passed
- 5 tests passed
- PR #9090 remote checks on `bbbb2d4627f5be17ca210dedb9edb91edd047df8`
- All Paperclip CI/status checks passed
- Greptile Confidence Score: 5/5, 0 comments added, 0 unresolved
Greptile threads
No route test changed because this PR does not change the route's
failed-automation query or normalization behavior.
## Risks
Low risk. The change only suppresses duplicate `automation_failed`
warnings when both `stageId` and `caseId` match. Distinct items in the
same stage still produce separate warnings.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5 coding agent in the Paperclip local adapter
environment; exact model snapshot and context-window metadata were not
exposed in the runtime. Tool use and code execution were enabled.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The server reports its own version through `server/src/version.ts`,
which is read by the `/health` endpoint and the telemetry client
> - When running from a cloned source tree, `server/package.json` is
frozen at the last published release version (e.g. `0.3.1`), so the
reported `serverVersion` never reflects how far the local checkout has
drifted from that release
> - Operators and support staff cannot tell from telemetry or health
output whether they are running a tagged release or a development build
with local commits on top
> - A `git describe --tags --match v* --long --dirty` call at startup
gives the exact nearest tag, number of commits since it, the current
SHA, and whether the tree is dirty — all the information needed to
compute a semantically meaningful version
> - This pull request replaces the static `pkg.version` export with a
`resolveServerVersion()` call that parses `git describe` output into
`YYYY.MDD.P+N.git.<sha>` (drift), `YYYY.MDD.P` (clean on-tag), or
appends `.dirty` for a modified tree, with a non-throwing fallback to
`package.json` when git is unavailable
> - The benefit is that from-source installs now report a version string
that lets operators and support quickly identify their exact checkout
state without running additional git commands
## Linked Issues or Issue Description
No pre-existing public issue. Inline description:
**What happened?**
When Paperclip is installed from source (git clone + pnpm), `GET
/health` and the telemetry envelope report the version frozen at the
last published `package.json` value (e.g. `0.3.1`) regardless of how
many commits ahead of that tag the local checkout is.
**Expected behavior**
The reported version should reflect the actual local state — nearest
release tag, number of commits since that tag, abbreviated commit SHA,
and a dirty marker when the working tree has uncommitted changes.
**Steps to reproduce**
Clone the repo, run `pnpm install && pnpm --filter @paperclipai/server
start`, then call `GET /health` or inspect telemetry envelopes. The
`serverVersion` field shows the `package.json` version even when the
checkout is dozens of commits ahead of that tag.
**Paperclip version or commit**
Affects all source-tree installs where `package.json` has not been
updated to match the current HEAD.
**Deployment mode**
Source install (git clone).
## What Changed
- `server/src/version.ts`: extracted `resolveServerVersion()` (replaces
the module-level `const serverVersion`) and `parseGitDescribeVersion()`
(exported for unit testing); the default implementation shells out to
`git describe --tags --match v* --long --dirty` with a 1 500 ms timeout;
falls back to `pkg.version ?? "0.0.0"` without throwing when git is
unavailable or the output cannot be parsed; replaced `logger` import
with a `console.debug`-based default to avoid pulling pino transport
side effects into a zero-dependency utility module
- `server/src/__tests__/version.test.ts`: 7-test unit suite covering
drift, clean on-tag collapse, dirty on-tag edge case, unparseable
fallback, `resolveServerVersion` happy path, and git-unavailable
fallback — all exercised via injected stubs without spawning a real git
process
## Verification
```sh
# Unit tests (7 tests)
pnpm exec vitest run server/src/__tests__/version.test.ts
# Type check
pnpm --filter @paperclipai/server typecheck
# Health and telemetry regression
pnpm exec vitest run server/src/__tests__/health.test.ts server/src/__tests__/telemetry-client-flush.test.ts
# Runtime smoke (from-source checkout)
# git describe --tags --match 'v*' --long => v2026.626.0-58-g518fc71ce
# server startup => serverVersion = 2026.626.0+59.git.3367571cc
```
All commands passed at the committed HEAD.
## Risks
Low. The change is additive and self-contained to
`server/src/version.ts`:
- `git describe` is called once at module load with a 1 500 ms timeout;
failure (non-git environment, git not on PATH, timeout) is silently
caught and falls back to `pkg.version`, preserving existing behavior for
published-package installs
- No API surface, database schema, or migration is touched
- The telemetry envelope already carried `serverVersion`; only the value
changes for source-tree installs
## Model Used
Claude Sonnet 4.6 (`claude-sonnet-4-6`) with tool use and code
execution. Context window: 200 k tokens.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [ ] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The browser UI depends on the Inter font family for its intended
visual baseline
> - The app previously referenced remote Google Fonts stylesheets at
runtime
> - That meant self-hosted, offline, or privacy-sensitive deployments
could lose the intended typography or depend on an external request
> - This pull request bundles the required Inter variable font files
with the UI and serves them from the app
> - A normal UI test now covers the static assets and CSS wiring without
adding a package script or build step
> - The benefit is a more reliable, self-contained UI that does not rely
on third-party webfont hosting
## Linked Issues or Issue Description
No public GitHub issue was found for this exact gap.
**Subsystem affected**
ui/ — React + Vite board UI
**Problem or motivation**
Paperclip's UI should ship the webfont assets it references so
production and self-hosted deployments render consistently without
reaching out to Google Fonts at runtime.
**Proposed solution**
Bundle the Inter variable font files under the UI public assets, load
them with local `@font-face` declarations, document the bundled assets,
and cover the source assets/CSS wiring with a normal UI Vitest test.
**Alternatives considered**
Keeping the remote stylesheet dependency is simpler, but leaves
deployments dependent on external font hosting. Using system fonts only
would avoid the asset footprint, but changes the intended UI typography.
**Roadmap alignment**
This is a focused UI reliability/polish fix, not a roadmap-level core
feature.
**Additional context**
Searched public GitHub issues and PRs for `webfonts
repo:paperclipai/paperclip`; no duplicates or closely related open items
were found.
## What Changed
- Added bundled Inter variable font assets and their notice under
`ui/public/fonts/`.
- Replaced remote Google Fonts imports with local `@font-face`
declarations using relative public-asset URLs that remain subpath-safe
from built CSS.
- Documented the local font asset expectation in development and UI spec
docs.
- Removed the follow-up font asset checker scripts and package/build
wiring after review feedback clarified they are not required for
building the UI.
- Added `ui/src/lib/ui-font-assets.test.ts` to verify the shipped WOFF2
files, notice text, and CSS font references through the normal UI test
suite.
## Verification
- `pnpm --filter @paperclipai/ui exec vitest run
src/lib/ui-font-assets.test.ts --config vitest.config.ts`
- Passed.
- Confirms the bundled font files exist, are WOFF2 files, have notice
coverage, and are referenced by `ui/src/index.css`.
- `pnpm --filter @paperclipai/ui build`
- Passed.
- Confirmed the UI still builds after removing the checker from
`ui/package.json`.
- Confirmed `ui/dist/fonts/` contains `InterVariable.woff2`,
`InterVariable-Italic.woff2`, and `NOTICE.md` after the build.
- The UI build emitted existing warnings about `::highlight(...)`, a
dynamic/static import overlap for `MarkdownEditor.tsx`, unresolved
relative public font URLs left for runtime resolution, and large chunks,
but completed successfully.
## Risks
Low risk. This adds static font assets and swaps the font source from a
remote stylesheet to same-origin files. The main tradeoff is a larger
repository/UI asset footprint from the bundled `.woff2` files.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5-based coding agent, tool-enabled terminal/GitHub
workflow with reasoning support.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The board UI is where operators inspect company activity, agent
work, and issue progress.
> - Existing board views show individual issue and run details, but they
do not give operators a compact time-based picture of work across
agents.
> - A work timeline helps operators scan when agents worked, how
handoffs happened, and where overlapping work occurred.
> - This pull request adds a company-scoped Work Timeline page backed by
the existing API surface and renders the timeline as a custom SVG
Gantt-style view.
> - The benefit is faster operator understanding of multi-agent
execution without opening each issue thread individually.
## Linked Issues or Issue Description
No public GitHub issue exists for this change.
Subsystem affected:
- ui/ — React + Vite board UI
Problem or motivation:
- Operators can inspect individual issues and runs, but there is no
compact time-based view of company work across agents.
- This makes it harder to scan overlaps, handoffs, retries, and activity
windows without opening many issue threads.
Proposed solution:
- Add a company-scoped Work Timeline page in the board UI.
- Render agent and system run spans as a custom SVG Gantt-style chart
with packed overlap lanes.
- Show issue color identity, kickoff attribution, hover-revealed
delegation connectors, retry styling, zoom controls, a sticky actor
gutter, and a minimap brush.
- Keep human activity lightweight by showing human kickoff chips without
plotting standalone human event rows.
Alternatives considered:
- Add the same information to existing issue-list or run-list views.
That would preserve simpler UI, but it would not show temporal overlap
or handoff paths clearly.
- Build this as a plugin-only surface. That keeps core smaller, but the
board already has the company-scoped route, navigation, and API client
patterns needed for this operator workflow.
Roadmap alignment:
- `ROADMAP.md` does not list an existing duplicate work-timeline
milestone. This supports the broader operator visibility direction
around artifacts, enforced outcomes, and higher-autonomy execution.
Additional context:
- Storybook includes `Pages/Work Timeline` stories for hour/day zoom and
a human-activity sample so reviewers can inspect the component without a
live backend.
## What Changed
- Added the Work Timeline page, route, sidebar entry, API client, query
key, and company-prefixed route helper coverage.
- Added a pure timeline layout transform for row packing, issue colors,
kickoff attribution, connector calculation, tick selection, and duration
formatting.
- Added the custom SVG timeline chart with sticky actor gutter,
hover-revealed connectors, zoom controls, minimap brushing,
visible-range feedback, and issue navigation.
- Added Storybook coverage plus sample fixtures for the work timeline.
- Added and corrected focused UI tests covering layout, chart behavior,
routing, sidebar behavior, and collapsed-sidebar expectations.
- Addressed Greptile feedback for kickoff fallback ordering, minimap
range math, document drag listener cleanup, and stable default `now`
handling.
## Verification
- `pnpm --filter @paperclipai/ui exec vitest run
src/lib/timeline/layout.test.ts
src/components/timeline/WorkTimelineChart.test.tsx
src/pages/Timeline.test.tsx src/lib/company-routes.test.ts
src/components/Sidebar.test.tsx
src/components/RequestCollapsedSidebar.test.tsx`
- `pnpm --filter @paperclipai/ui typecheck`
- `git merge-tree $(git merge-base HEAD origin/master) HEAD
origin/master | rg -n "<<<<<<<|changed in both|CONFLICT"` returned no
conflicts.
- Attempted Storybook screenshot capture with Playwright; Storybook ran
locally, but Chromium could not launch in this container because native
browser libraries such as `libatk-1.0.so.0` are unavailable and `npx
playwright install-deps chromium` requires interactive sudo.
## Risks
- Medium UI risk: this adds a substantial visual surface with custom SVG
interaction logic, so browser-level review is still useful for
responsive behavior and usability.
- Low backend risk: this PR only adds a UI client/page around the
existing timeline API contract and does not change database schema or
server routes.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI GPT-5 via Codex coding agent, with repository file access, shell
command execution, GitHub connector access, and focused test execution.
Exact context-window details are not exposed in this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - When you swap an agent's adapter (e.g. from one LLM provider to
another), the server merges the incoming PATCH body with stored config —
keys listed in \`ADAPTER_AGNOSTIC_KEYS\` are preserved regardless of
which adapter is active
> - That constant was defined independently in two places:
\`server/src/agents.ts\` (used by the adapter-swap route) and
\`ui/src/lib/agent-config-patch.ts\` (used by the UI patch builder)
> - PR #8975 fixed the bug where \`paperclipSkillSync.desiredSkills\`
was dropped on adapter swap by adding it to the server-side constant,
but the UI-side copy was not updated in the same PR — creating ongoing
drift risk
> - This pull request hoists \`ADAPTER_AGNOSTIC_KEYS\` into
\`packages/shared\` so both consumers import the same constant
> - The benefit is a single source of truth: any future key addition is
made in one place and both the server route and the UI patch builder
pick it up automatically, with a drift guard to catch any accidental
re-duplication
## Linked Issues or Issue Description
Refs #8975 — follow-up deduplication: #8975 fixed the runtime bug but
left the constant duplicated across server and UI. This PR closes that
gap.
## What Changed
- Added \`ADAPTER_AGNOSTIC_KEYS\` constant and \`AdapterAgnosticKey\`
type to \`packages/shared/src/adapter-agnostic-keys.ts\`
- Updated \`server/src/agents.ts\` to import the shared constant,
removing the local copy
- Updated \`ui/src/lib/agent-config-patch.ts\` to import the shared
constant, removing the local copy
- Added \`packages/shared/src/adapter-agnostic-keys.test.ts\`: drift
guard asserting the expected key set and both consumer import sites
## Verification
\`\`\`bash
pnpm exec vitest run packages/shared/src/adapter-agnostic-keys.test.ts
ui/src/lib/agent-config-patch.test.ts
server/src/__tests__/agent-instructions-routes.test.ts
pnpm --filter @paperclipai/shared typecheck
pnpm --filter @paperclipai/server typecheck
pnpm --filter @paperclipai/ui typecheck
\`\`\`
All 15 tests pass across the three files; all three packages typecheck
clean.
## Risks
Low risk — behavior-preserving refactor. The key set is unchanged; only
the import source changes. The drift guard will fail loudly if someone
accidentally re-introduces a local copy or modifies one without updating
the other.
> For core feature work, check [\`ROADMAP.md\`](ROADMAP.md) first and
discuss it in \`#dev\` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See \`CONTRIBUTING.md\`.
## Model Used
- Provider: Anthropic
- Model: Claude Sonnet 4.6 (\`claude-sonnet-4-6\`)
- Context: standard context window, tool use enabled
- Reasoning: standard mode (no extended thinking)
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with \`Fixes: #\` /
\`Closes #\` / \`Refs #\` OR (b) described the issue in-PR following the
relevant issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub \`#NNN\` /
\`github.com/paperclipai/paperclip\` URLs)
- [ ] My branch name describes the change (e.g. \`docs/...\`,
\`fix/...\`) and contains no internal Paperclip ticket id or
instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agent runs often need provider credentials, API tokens, and other
environment-bound secrets.
> - Company-level secrets work for shared credentials, but they do not
model values that should differ by human operator.
> - Without a user-scoped model, a run can dispatch without knowing
whether the responsible human has supplied the needed value.
> - Paperclip also needs run attribution to make those user-scoped
runtime checks deterministic and auditable.
> - This pull request adds user-specific secret definitions, per-user
values, environment bindings, responsible-user attribution, and runtime
resolution gates.
> - The benefit is that teams can define the secret once, let each user
provide their own value, and block runs before dispatch when required
user secrets or active definitions are unavailable.
## Linked Issues or Issue Description
Refs #224
Refs #6057
This PR implements user-specific secret support as a core
secret-management capability rather than a one-off adapter setting. It
is related to existing public work on company secrets UI and runtime
secret refs, but is distinct because the value is owned by the
responsible user and resolved at run dispatch time.
Related PR search before opening found existing secrets work such as
#1550, #8256, #8614, #8634, and #8647; none of those add the full
user-secret definition/value/runtime gate covered here.
## What Changed
- Added user-secret definitions and per-user "My secrets" values,
keeping stored values out of access metadata.
- Added `user_secret_ref` environment bindings and UI affordances to
pick them alongside existing secret refs.
- Added responsible-user runtime resolution so user-secret refs resolve
against the human responsible for the run.
- Added pre-dispatch missing-secret gates so runs fail before adapter
dispatch when required user values are absent or definitions are
inactive.
- Added low-trust allowlist hardening for user-secret runtime access.
- Added issue, routine, run, and agent API key responsible-user
attribution and fail-closed dispatch behavior when attribution cannot be
resolved.
- Added denial-copy mapping so responsible-user authorization failures
surface as actionable run outcomes instead of opaque setup failures.
- Added OpenAPI documentation for the user-secret routes.
- Rebases cleanly on current `master`; migrations were renumbered
incrementally as `0128_user_specific_secrets`,
`0129_agent_api_key_responsible_user`, and
`0130_run_responsible_user_invariant` after upstream `0126`/`0127`
migrations.
- Removed previously committed local design screenshots so the PR
contains code/docs/tests only.
## Verification
- PASS: PR head `2527febd106bcf3ca264ca0da7fca491084192d6` is based on
`paperclipai/paperclip:master`.
- PASS: `git diff --check`
- PASS: `git diff --name-only public/master...HEAD | rg
'^(pnpm-lock\\.yaml|\\.github/workflows/|screenshots/)' || true`
produced no files.
- PASS: migration journal audit confirmed unique indexes through `130`
with tail entries `0126_issue_comment_derived_attribution`,
`0127_environment_custom_images_instance_scoped`,
`0128_user_specific_secrets`, `0129_agent_api_key_responsible_user`, and
`0130_run_responsible_user_invariant`.
- PASS: `pnpm --filter @paperclipai/ui typecheck`
- PASS: `pnpm --filter @paperclipai/server typecheck`
- PASS: `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/heartbeat-responsible-user-invariant.test.ts`
- PASS: `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/heartbeat-active-run-output-watchdog.test.ts
src/__tests__/heartbeat-stale-queue-invalidation.test.ts
src/__tests__/heartbeat-workspace-finalize-branch.test.ts
src/__tests__/issue-monitor-scheduler.test.ts`
- PASS: `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/heartbeat-comment-wake-batching.test.ts
src/__tests__/heartbeat-retry-scheduling.test.ts
src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts
src/__tests__/heartbeat-plugin-environment.test.ts`
- PASS: `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/low-trust-red-team-routes.test.ts`
- PASS: `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/secrets-service.test.ts` (55 tests)
- PASS: `pnpm vitest run server/src/__tests__/secrets-routes.test.ts
server/src/__tests__/secrets-service.test.ts` (89 tests after final
Greptile cleanup fixes)
- PASS: `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/heartbeat-issue-liveness-escalation.test.ts` (17 tests
after the final rebase CI fix)
- PASS: focused server Vitest batches covering heartbeat recovery,
project env, plugin env, routines, low-trust, pipelines, monitors,
watchdog, and stale queue paths.
- PASS: GitHub checks are green on
`2527febd106bcf3ca264ca0da7fca491084192d6`, including Typecheck +
Release Registry, Build, General tests, serialized server suites, e2e,
Canary Dry Run, verify, security checks, and Greptile Review.
- PASS: Greptile Review completed successfully on
`2527febd106bcf3ca264ca0da7fca491084192d6` with Confidence Score 5/5,
and GraphQL review-thread audit returned zero unresolved non-outdated
threads.
## Risks
- Runtime behavior now depends on a run having a correct responsible
user; missing or incorrect responsibility assignment can block runs
before adapter dispatch.
- `user_secret_ref` bindings intentionally expose metadata without
values, but UI/API callers may need to handle the new binding kind
explicitly.
- External secret providers and IAM policies are not automatically
provisioned by this PR; operators still need to configure provider-side
access for non-local vaults.
- The PR is broad across db/shared/server/UI/runtime paths, so release
validation should include both API and UI secret workflows before merge.
- The migration renumbering is intentionally incremental after upstream
migrations; the branch migrations use guarded
column/table/index/constraint creation so users who tested the older
draft numbering should not hit duplicate DDL for the existing objects.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5-based coding agent (`gpt-5`), Codex local adapter
with shell/tool use and code execution. Context window and internal
reasoning mode are not exposed by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Each agent runs on an adapter (`claude_local`, `codex_local`, …) and
can be assigned company skills that are synced into its runtime
> - An agent's desired-skill selection is persisted inside its single
`adapterConfig` JSON blob under `paperclipSkillSync`, even though the
selection is a company-level, adapter-agnostic choice
> - When a user changes an agent's adapter type, both the server PATCH
handler and the UI patch builder rebuild `adapterConfig` and carry over
only a hardcoded allow-list of adapter-agnostic keys (`env`, `cwd`,
instructions bundle, …)
> - `paperclipSkillSync` was missing from both allow-lists, so switching
adapters (e.g. claude_local → codex_local) silently wiped every assigned
skill
> - This pull request adds `paperclipSkillSync` to the adapter-agnostic
preservation list on both layers and covers it with regression tests
> - The benefit is that switching an agent's adapter no longer destroys
its skill configuration — skills are preserved exactly like
env/cwd/instructions already are
## Linked Issues or Issue Description
Fixes#8974
## What Changed
- **Server (authoritative fix)** — `server/src/routes/agents.ts`: added
`"paperclipSkillSync"` to the `ADAPTER_AGNOSTIC_KEYS` list in the
`changingAdapterType` branch of `PATCH /agents/:id`. On an adapter-type
change the handler now restores the skill-sync selection from the
existing persisted config when the incoming config omits it — the same
mechanism already used for `env`, `cwd`, and the instructions bundle.
This protects every API/CLI client, not just the UI.
- **UI (defense in depth)** — `ui/src/lib/agent-config-patch.ts`: added
`"paperclipSkillSync"` to the client-side `ADAPTER_AGNOSTIC_KEYS` in
`buildAgentUpdatePatch`, so the optimistic patch the client builds on an
adapter switch stops stripping the key before it reaches the server.
- **Tests** — added regression tests on both layers:
- `server/src/__tests__/agent-instructions-routes.test.ts`: `PATCH`ing
`adapterType` (claude_local → codex_local) with `replaceAdapterConfig:
true` keeps `adapterConfig.paperclipSkillSync`.
- `ui/src/lib/agent-config-patch.test.ts`: `buildAgentUpdatePatch`
preserves `paperclipSkillSync` when the overlay changes the adapter
type.
## Verification
```
# server (run from repo root)
cd server && ../node_modules/.bin/vitest run \
src/__tests__/agent-instructions-routes.test.ts \
src/__tests__/agent-skills-routes.test.ts \
src/__tests__/agent-adapter-validation-routes.test.ts \
src/__tests__/agent-permissions-routes.test.ts
# 83 passed
../node_modules/.bin/tsc --noEmit -p tsconfig.json # clean
# ui
cd ui && ./node_modules/.bin/vitest run src/lib/agent-config-patch.test.ts # 7 passed
pnpm --filter @paperclipai/ui typecheck # clean
```
Both new tests fail without the corresponding source change (verified
red → green).
Manual: create an agent on `claude_local`, assign skills, switch it to
`codex_local`, and confirm `GET /api/agents/:id/skills` still returns
the desired skills.
## Risks
Low risk.
- The change only *adds* one key to an existing preservation allow-list;
it does not alter how any other key is handled. Behavior for agents
without a `paperclipSkillSync` block is unchanged (the key is simply
absent and nothing is copied).
- `paperclipSkillSync` is adapter-agnostic (company skill keys, not
adapter-specific), so carrying it across an adapter switch is always
safe — a target adapter that does not support skill sync just ignores
it, and switching back restores the selection.
- Same-adapter config edits already merged and preserved the key; this
only closes the adapter-type-change gap, matching the existing
env/cwd/instructions behavior.
- Follow-up (not in this PR to keep it minimal): the server and client
`ADAPTER_AGNOSTIC_KEYS` lists are maintained separately and already
diverge (`instructionsFilePath` is client-only); a shared constant could
prevent future drift.
## Model Used
Claude Opus 4.8 (`claude-opus-4-8`, 1M-token context), extended thinking
enabled, with tool use (file edit, shell, GitHub CLI) via Claude Code. A
read-only sub-agent was used to trace the root cause across the server
and UI layers.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work (bug fix, not a feature)
- [x] I have searched GitHub for duplicate or related PRs and linked
them above (none found)
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change
(`fix/preserve-skills-on-adapter-type-switch`) and contains no internal
Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes (N/A —
internal config-preservation fix, no user-facing docs or API contract
change)
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green (pending CI on this PR)
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
(pending review)
- [x] I will address all Greptile and reviewer comments before
requesting merge
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agent heartbeats provision execution workspaces before invoking
local or sandboxed adapters.
> - Some follow-up issues intentionally request `reuse_existing` so they
continue in an inherited execution workspace.
> - The heartbeat provisioning path treated missing or archived
workspace rows as if no explicit reuse request existed.
> - That could silently realize and persist a fresh project/default
workspace over an explicit inherited-workspace binding.
> - This pull request keys explicit reuse off the issue preference and
workspace id, then either restores that workspace or fails with a
structured workspace validation error.
> - The benefit is that intentional workspace inheritance remains
auditable and does not silently degrade into unrelated fallback
workspaces.
## Linked Issues or Issue Description
Refs #8058
Refs #6036
Refs #2203
This fixes a narrower heartbeat provisioning bug around explicit
`reuse_existing` issue runs: if the target inherited execution workspace
is missing, archived, or fails restore, provisioning now reports the
reuse failure instead of replacing the issue's workspace binding with a
freshly realized fallback.
## What Changed
- Added explicit helpers for resolving workspace reuse requests and
deciding whether reuse should restore, refresh metadata, or keep prior
replacement-class drift visible.
- Changed heartbeat workspace provisioning so explicit `reuse_existing`
requests go through restore-or-fail behavior instead of falling back to
`realizeExecutionWorkspace` when the stored workspace row is
unavailable.
- Added structured `workspace_validation_failed` details for inherited
workspace reuse failures.
- Added regression coverage for replacement-class drift, restore errors,
missing rows, archived rows, and restore misses.
## Verification
- `pnpm install --frozen-lockfile`
- `pnpm --filter @paperclipai/plugin-sdk ensure-build-deps`
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/heartbeat-workspace-session.test.ts`
- `pnpm --filter @paperclipai/server typecheck`
- `git diff --check origin/master...HEAD`
- Scanned the branch diff and commit messages for credentials, tokens,
private URLs, PII-style values, and internal issue links before pushing;
no unsafe hits remained.
## Risks
- Explicit reuse requests whose stored workspace cannot be restored now
fail the run instead of opportunistically creating a replacement
workspace. That is intentional, but it may surface stale or archived
workspace rows as visible provisioning failures that require repair.
- Non-reuse workspace provisioning still uses the existing realization
path, so the behavior shift is scoped to issues that explicitly request
existing workspace reuse.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI GPT-5 via Codex local agent, with shell/tool use enabled for
repository inspection, code editing, verification, git, and GitHub CLI
operations. Runtime context-window details were not exposed by the
adapter.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The agent detail page is where operators inspect heartbeat runs and
watch live execution output.
> - Heartbeat runs can publish progress events while longer operations
are happening.
> - The live log viewer already appended streamed log and structured run
events, but it ignored progress events for the same run.
> - That made useful progress text invisible in the run log until
another event type arrived or the operator inspected other surfaces.
> - This pull request renders run progress events as system log lines in
the live agent run viewer.
> - The benefit is clearer live feedback during long-running heartbeat
operations without changing the backend event contract.
## Linked Issues or Issue Description
No public GitHub issue exists, so this PR describes the issue inline
following the bug report template.
### What happened
The agent detail run log subscribed to company live events and handled
`heartbeat.run.log` plus structured `heartbeat.run.event` payloads, but
it ignored `heartbeat.run.progress` events for the active run.
### Expected behavior
When a heartbeat run emits a progress message, the active run log should
show that message immediately as operator-visible system output.
### Steps to reproduce
1. Open an agent detail page for a live heartbeat run.
2. Trigger a run operation that emits `heartbeat.run.progress` events
with a `message` and optional `phase`.
3. Watch the live log viewer.
Before this change, the progress event was ignored by the log viewer.
After this change, it appears as a system log line, prefixed by
`[phase]` when a phase is present.
### Paperclip version / deployment mode
Current `master`; local development and normal board UI deployments.
### Related work search
Searched public GitHub issues and PRs in `paperclipai/paperclip` for
`heartbeat.run.progress AgentDetail` and `run progress log viewer`; no
duplicate issue or PR was found.
## What Changed
- Added live handling for `heartbeat.run.progress` events in
`AgentDetail`'s run `LogViewer`.
- Render progress messages as `system` log lines for the matching run.
- Include the optional progress phase in the displayed line as `[phase]
message`.
- Prefer the event's `updatedAt` timestamp when provided, falling back
to the live event timestamp.
- Added a replay key for progress log lines so WebSocket reconnect
replay does not duplicate the same rendered progress line.
- Added focused formatter/key tests covering phased progress, unphased
progress, empty messages, and replay-key output.
### Visual output example
The rendered log text is covered by the new formatter test:
```text
[workspace] Syncing issue history
Preparing workspace
```
No layout or styling changes are included; this PR only makes existing
log-line UI receive one more live event type.
## Verification
- `pnpm install --frozen-lockfile` — completed; emitted non-fatal
bin-link warnings for the unbuilt plugin SDK dev CLI.
- `pnpm --filter @paperclipai/ui typecheck` — passed.
- `pnpm --filter @paperclipai/ui exec vitest run
src/pages/AgentDetail.progress.test.ts
src/context/LiveUpdatesProvider.test.ts` — passed, 2 files / 26 tests.
- `git diff --check` — passed.
- Local sensitive-content scan over the PR diff using patterns for API
keys, tokens, secrets, passwords, auth headers, private keys,
localhost/private paths, internal ticket ids, agent links, and tailnet
markers — no findings.
## Risks
Low risk. This is a UI-only live-event handling change for an existing
event type. The replay guard is intentionally scoped to progress lines
and uses the rendered timestamp, stream, and chunk as the key, so
repeated progress events with distinct timestamps or messages still
appear.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5 coding agent with repository tool use, shell
execution, GitHub CLI access, and local test execution. Context window
size was not exposed in this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Auto-generated lockfile refresh after dependencies changed on master.
This PR only updates pnpm-lock.yaml.
Co-authored-by: lockfile-bot <lockfile-bot@users.noreply.github.com>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Environment sandboxes already support custom image creation and
refresh through a temporary SSH setup session.
> - The existing workflow makes operators copy an SSH command into an
external terminal before they can install packages or make image
changes.
> - That extra context switch is slower, easier to get wrong, and less
integrated with the setup session Paperclip already tracks.
> - This pull request adds an embedded browser SSH terminal for custom
image setup, so operators can start working in the target sandbox
directly from the environment configuration flow.
> - The implementation uses short-lived websocket attachment tokens,
session-lifetime SSH host-key pinning, and server-managed terminal
cleanup so the feature fits the existing setup-session boundary.
> - The benefit is a smoother custom image creation and refresh
experience without asking users to leave Paperclip for routine sandbox
setup work.
## Linked Issues or Issue Description
No public GitHub issue exists.
### Subsystem affected
Cross-cutting: `server/` custom image setup APIs and websocket handling,
`ui/` environment configuration UI, and shared custom image contracts.
### Problem or motivation
Custom image creation and refresh require an operator to open a separate
SSH client, paste the command shown by Paperclip, perform setup work,
then return to the browser to finish the image flow. This is functional
but awkward for a setup process that already starts and tracks a
temporary sandbox session.
### Proposed solution
Embed an SSH terminal in the custom image setup UI. When a setup session
exposes an SSH payload, Paperclip should open a browser terminal backed
by a server-side websocket session, let the operator run setup commands
in-place, and then close the terminal when setup is finished, cancelled,
expired, or disconnected.
### Alternatives considered
- Keep the existing copy/paste SSH command workflow. This remains a
fallback, but it does not streamline the common path.
- Put SSH credentials directly into websocket URLs. This was avoided so
terminal authentication can happen in an explicit first websocket auth
frame rather than in logged URLs.
- Trust the SSH host blindly for every reconnect. This PR instead pins
the observed host-key fingerprint for the setup-session lifetime.
### Roadmap alignment
This fits the roadmap theme of making agent workspaces usable in more
remote and sandboxed environments while preserving Paperclip's
control-plane model.
### Additional context
Public GitHub search did not find a duplicate issue or PR for `custom
image terminal ssh` in `paperclipai/paperclip`.
## What Changed
- Added server-side terminal session tracking for custom image setup
sessions, including connect-token issuance, websocket attachment,
expiry, resize, input, and shutdown handling.
- Added an embedded browser terminal to the custom image creation and
refresh flow when a setup session provides SSH connection details.
- Moved terminal token authentication out of the websocket URL and into
the first websocket JSON auth frame.
- Added SSH host-key SHA-256 pinning for each terminal session and
documented the provider convention for username-embedded SSH
credentials.
- Updated the custom image environment API and UI so the setup terminal
can open, reconnect, show status, authenticate, resize, and remain
active for the setup-session lifetime once attached.
- Kept custom image setup routes company-scoped and closed active
terminal sessions on setup finish/cancel.
- Added focused unit/integration/UI coverage for token expiry,
setup-session expiry, websocket close paths, host-key pinning, and
terminal session lifecycle behavior.
- Removed the generated lockfile delta from the PR; CI owns temporary
lockfile regeneration for manifest-changing PRs.
## Verification
- `pnpm exec vitest run
server/src/__tests__/server-startup-feedback-export.test.ts
server/src/__tests__/environment-custom-image-terminal-ws.test.ts
server/src/services/environment-custom-image-terminal-sessions.test.ts
server/src/__tests__/environment-custom-image-routes.test.ts
packages/shared/src/environment-custom-images.test.ts
ui/src/pages/CompanyEnvironments.test.tsx`
- 6 test files passed
- 58 tests passed
- `pnpm --filter @paperclipai/server typecheck`
- `pnpm --filter @paperclipai/ui typecheck`
- `pnpm --filter @paperclipai/server build`
- `pnpm --filter @paperclipai/ui build`
- `pnpm run typecheck:build-gaps`
- `git diff --check`
- Local sensitive-content scan over the PR diff using patterns for API
keys, private keys, private hostnames, local paths, token fields, and
credential-like strings.
- Findings were limited to removed URL-token code and synthetic test
placeholders such as `ssh-token-secret` and
`terminal-token-terminal-token-123456`.
- No real credentials, private hostnames, local filesystem paths, or
instance-local links were found.
- Remote PR checks were green after the implementation commit, including
Build, Typecheck + Release Registry, General tests, serialized server
suites, e2e, verify, Socket, Snyk, Superagent, and Greptile 5/5.
- Post-merge PR hardening on July 3, 2026: merged `origin/master` at
`47448721e` into the branch, resolved the `CompanyEnvironments.tsx`
import conflict, reran focused tests, server/UI typechecks, server/UI
builds, `pnpm run typecheck:build-gaps`, and `git diff --check`, scanned
the final diff for sensitive content, pushed `4b43558cc`, and confirmed
all remote checks plus Greptile 5/5 were green.
- PR metadata correction on July 3, 2026: changed the title/body framing
from bug-fix language to feature-request language. No source files
changed for this metadata-only update.
## Risks
- Moderate surface area because this adds websocket routing,
setup-session runtime state, package dependencies, and a new custom
image UI path.
- New websocket attachments still require valid short-lived tokens;
established terminal sessions remain bounded by setup-session expiry,
explicit finish/cancel, client close, or server shutdown.
- The terminal-session store is in-memory, so active terminal websocket
tokens and host-key pins do not survive server restarts.
- SSH host-key verification uses session-lifetime TOFU pinning because
the current provider payload does not expose a trusted host-key
fingerprint.
- The external SSH command remains important as a fallback if a browser,
proxy, or network environment cannot sustain the websocket terminal.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5 coding agent with shell/tool execution. Context
window size was not exposed in this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The issue details sidebar is a high-traffic operator surface for
scanning task state, ownership, policy, relationships, and external
references.
> - The previous properties pane mixed too much behavior in one large
component and several rows could overflow or become hard to scan with
long labels and relation lists.
> - The UI needed a narrower, more reusable structure so compact
property rows, relation pills, external URL rows, and picker triggers
behave consistently.
> - This pull request splits the properties pane into focused helper
modules and tightens the pane's layout, truncation, popover, and
overflow behavior.
> - The benefit is a denser, more stable properties pane that stays
usable when issues have long titles, many relationships, external URLs,
or execution policy IDs.
## Linked Issues or Issue Description
No public issue exists for this work. I searched GitHub issues and PRs
for `IssueProperties properties pane`; there was no duplicate issue and
the matching PRs were unrelated test stabilization or other work.
### Problem or motivation
The board issue details properties pane is a frequent operator workflow
surface, but it was implemented as one large component and several rows
could become hard to scan with long labels, many relationships, external
URLs, or execution policy IDs.
### Proposed solution
Split the properties pane into focused modules, tighten compact row
layout and truncation behavior, add bounded previews with explicit
expansion controls for long relation and URL lists, and make execution
policy ID generation work on insecure origins as well as normal browser
origins.
### Alternatives considered
A smaller patch inside the existing monolithic component would fix
individual overflow symptoms, but it would keep related primitives,
picker behavior, relation controls, and external URL rendering tangled
in one file. The split keeps the behavior easier to test and review
without changing public APIs.
### Roadmap alignment
This is an incremental UI quality improvement to the existing board task
details surface. I checked `ROADMAP.md` and did not find overlapping
planned core feature work.
## What Changed
- Split the issue properties pane into focused modules for helpers,
primitives, relation controls, property pickers, and external object
rows.
- Cleaned up row spacing, truncation, picker trigger alignment, scroll
behavior, status color coverage, and long-value titles.
- Added bounded previews and expand/collapse controls for blocking,
sub-task, related-task, and external URL lists.
- Fixed execution policy ID generation so insecure origins fall back to
a stable base URL instead of throwing.
- Updated Storybook issue-management stories and expanded unit coverage
for the new properties pane behavior.
## Verification
- `git diff --check origin/master..HEAD`
- `pnpm --filter @paperclipai/ui exec vitest run
src/components/IssueProperties.test.tsx` — 38 tests passed
## Risks
Low to moderate risk. The changes are UI-only, but they touch a
frequently used task details surface. The main risk is a subtle layout
regression in an untested viewport or issue shape; the branch adds
targeted coverage for long relation and external URL lists.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI GPT-5 Codex coding agent with repository tool use, shell
execution, GitHub CLI access, and local test execution. Context window
size was not exposed in this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
## Thinking Path
> - Paperclip is the open source control plane people use to manage AI
agents for work.
> - Environment variables and secrets sit in the configuration surfaces
that let agents, projects, routines, and company environments run with
the right runtime inputs.
> - The previous editor was a single legacy component with cramped row
behavior, weak secret conversion affordances, and duplicated handling
across several call sites.
> - Operators need a clearer editor that handles text values, secret
references, draft rows, and sensitive-value warnings consistently
wherever environment variables are configured.
> - This pull request replaces the legacy editor with a reusable
environment variables editor and migrates the existing configuration
surfaces to it.
> - The benefit is a more reliable editing workflow with targeted test
coverage around row state, dotenv parsing, secret selection, and
affected page integrations.
## Linked Issues or Issue Description
No public GitHub issue exists, so this PR describes the issue inline
following the feature request template.
### Subsystem affected
ui/ — React + Vite board UI
### Problem or motivation
Environment variables are edited in several Paperclip configuration
surfaces, including agent config, project properties, stage secrets,
routine sections, company environments, and company settings. The legacy
editor made common operator work difficult: rows could feel cramped,
secret conversion was inconsistent, draft rows and imported dotenv data
were easy to mishandle, and sensitive-value warnings did not have a
consistent place in the workflow.
### Proposed solution
Introduce a reusable environment variables editor component that
consistently supports text values, secret references, draft rows, dotenv
import parsing, sensitive-value hints, secret picking, secret creation,
and conversion to stored secrets. Migrate the existing
environment-variable call sites to the shared editor so behavior and
tests live in one component family.
### Alternatives considered
Keeping the existing `EnvVarEditor` and patching individual call sites
would preserve duplication and leave each surface responsible for its
own row and secret handling. This PR instead centralizes the behavior so
future fixes cover all migrated surfaces.
### Roadmap alignment
Checked `ROADMAP.md`; this does not duplicate a named roadmap item. It
supports the existing local-first and deployment-oriented product
direction by improving the UI where operators configure runtime
environment values.
### Additional context
The PR includes targeted tests for the editor model, dotenv parsing,
sensitive-value detection, component behavior, affected page
integrations, and Greptile review regressions around external saves and
bulk import immutability.
## What Changed
- Replaced the legacy `EnvVarEditor` with a reusable
`environment-variables-editor` component family.
- Added editor model helpers for draft rows, dotenv parsing,
sensitive-value detection, secret picking, secret creation, and
conversion to secret references.
- Migrated agent config, project properties, stage secrets, routine
editable sections, company environments, company settings, design guide
examples, and Storybook stories to the new editor.
- Added targeted tests for the editor model, parsing, sensitive-value
detection, component behavior, and affected company environment/settings
integrations.
- Fixed the company settings test harness to use the repo’s
`flushSync`-based React test helper pattern under the current React
build.
- Addressed Greptile feedback by flushing pending editor drafts before
enclosing form submits or external save-button clicks, cloning
bulk-import rows before mutation, and deferring the overflow
store-as-secret popover open path.
## Verification
- `pnpm exec vitest run
ui/src/components/environment-variables-editor/EnvironmentVariablesEditor.test.tsx
ui/src/pages/CompanyEnvironments.test.tsx
ui/src/components/AgentConfigForm.render.test.tsx` — passed, 3 files /
40 tests.
- Earlier focused Vitest coverage for model, dotenv parsing, sensitive
detection, company environments, and company settings passed, 6 files /
78 tests.
- `pnpm --filter @paperclipai/ui typecheck` — passed.
- GitHub PR checks on head `0aa49c6f8afed1f62d9e26da07fc466fbf299850` —
passed; CI checks green, security review neutral, Greptile check
success.
- Greptile review — 5/5 confidence on head
`0aa49c6f8afed1f62d9e26da07fc466fbf299850`; 0 unresolved review threads.
## Risks
- Medium UI risk: several environment-variable entry surfaces now share
the new editor, so regressions could affect multiple configuration
workflows at once.
- Secret conversion, draft-row behavior, external save flushing, and
bulk import behavior are covered by targeted tests, but reviewer
attention should still focus on manual editing flows, focus retention,
and save/cancel affordances.
- No database or API contract changes.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- OpenAI Codex, GPT-5-based coding agent with tool use and local command
execution; medium reasoning mode. Exact context-window metadata is not
exposed in this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - A core part of that experience is watching active agent runs without
dropping into raw logs first
> - Local and sandbox-backed adapters already record useful run output,
progress, and tool activity
> - But active issue threads could sit visually stale while the agent
was syncing workspaces, tailing sandbox output, or emitting incremental
tool-call updates
> - Operators need timely, human-readable progress while preserving the
raw transcript underneath
> - This pull request streams sandbox run-log progress into runtime
status, keeps visible issue threads refreshed, and folds repeated ACPX
tool updates into stable transcript cards
> - The benefit is that long-running agent work becomes easier to
supervise without changing the task/comment control-plane model
## Linked Issues or Issue Description
No public GitHub issue exists for this exact change.
Problem/motivation:
- During long-running sandboxed agent work, the issue UI can appear idle
even though the agent is actively syncing, running tools, or producing
incremental output.
- Operators need realtime feedback at the issue-thread layer, not only
after opening raw logs or waiting for the final heartbeat result.
- Related public context: #1808 previously added live-run status dots to
Projects; #4362 touches heartbeat wakeup behavior but is not a duplicate
of this runtime/UI feedback change.
## What Changed
- Added sandbox run-log streaming support and defaulted sandbox-capable
local adapters into the richer live-feedback path.
- Surfaced environment/sandbox sync progress through heartbeat runtime
status with bounded, redacted snippets.
- Added live issue-thread cache patching so visible active runs update
as progress events arrive.
- Folded repeated ACPX `tool_call` updates into one transcript card
instead of stacking duplicate cards.
- Updated adapter docs and added focused regression coverage for sandbox
log streaming, runtime status, ACPX parsing, live updates, transcript
rendering, and issue chat messages.
## Verification
- `pnpm install --frozen-lockfile`
- `pnpm exec vitest run ui/src/context/LiveUpdatesProvider.test.ts`
- `pnpm exec vitest run
server/src/services/heartbeat-run-runtime-status.test.ts
server/src/__tests__/heartbeat-runtime-state.test.ts
ui/src/context/LiveUpdatesProvider.test.ts`
- `pnpm exec vitest run
packages/adapter-utils/src/execution-target-sandbox.test.ts
packages/adapter-utils/src/sandbox-managed-runtime.test.ts
server/src/services/heartbeat-run-runtime-status.test.ts
server/src/__tests__/agent-live-run-routes.test.ts
server/src/__tests__/heartbeat-runtime-state.test.ts
packages/adapters/acpx-local/src/ui/parse-stdout.test.ts
ui/src/context/LiveUpdatesProvider.test.ts
ui/src/components/transcript/RunTranscriptView.test.tsx
ui/src/lib/issue-chat-messages.test.ts
ui/src/components/IssueChatThread.test.tsx`
- GitHub PR workflow on head `8397953e7b41ccd42e5d9457ee7e4dfb996e4ec5`:
`verify`, build, typecheck/release-registry, e2e, general shards,
serialized server shards, and canary dry run passed.
- Greptile Review on head `8397953e7b41ccd42e5d9457ee7e4dfb996e4ec5`:
Confidence Score 5/5, no unresolved review threads.
## Risks
- Live issue-thread cache patching could miss an edge case for a route
shape not covered by tests.
- Surfacing active-run snippets needs continued care around redaction;
this PR keeps snippets bounded and adds redaction-focused coverage.
- More frequent active-run UI refreshes could expose performance issues
on very large issue threads, though updates are scoped to visible
run/query caches.
## Model Used
OpenAI GPT-5 via Codex, operating as a tool-enabled coding agent with
shell, git, and repository-editing capabilities. Context window size is
not exposed in this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Adapter names are part of the board-facing agent setup and
management experience.
> - The product now treats adapters as harnesses, while execution
environments are modeled separately.
> - Several built-in adapter labels still carried legacy local wording
from the older harness-by-environment model.
> - That wording makes the UI noisier and implies a distinction users no
longer need to reason about.
> - This pull request normalizes adapter display labels while keeping
persisted adapter type identifiers unchanged.
> - The benefit is clearer adapter selection and management copy without
a database migration.
## Linked Issues or Issue Description
No public GitHub issue was found for this exact cleanup.
Related public PRs:
- Supersedes #8910, an earlier branch for the same cleanup that did not
include the later docs/gateway/Cursor alignment.
- Refs #8819, which is related display-registry work for external
multi-segment adapter labels, but not a duplicate of this built-in label
cleanup.
Feature request details:
- Subsystem affected: Cross-cutting (`ui/`, `packages/adapters`, and
docs).
- Problem or motivation: user-facing adapter names include legacy local
qualifiers even though adapters map to harnesses and environments are
first-class elsewhere.
- Proposed solution: remove the legacy local wording from built-in
display labels, keep machine-readable adapter type ids unchanged, and
keep gateway disambiguation where it is useful.
- Alternatives considered: changing persisted adapter type ids was ruled
out because it would create migration and compatibility risk; one-off UI
replacements were ruled out because the display registry is already the
correct central label boundary.
- Roadmap alignment: this is small adapter UX polish, not a new
roadmap-level core feature.
## What Changed
- Updated the adapter display registry so known adapter labels are final
and no built-in local adapter renders a legacy local suffix.
- Preserved clean derived labels for unknown plugin local types while
keeping gateway disambiguation for unknown gateway types.
- Updated `AdapterManager` to prefer registry labels when the server
reports raw adapter type ids for built-ins.
- Removed legacy local wording from built-in adapter metadata labels in
UI and adapter packages.
- Aligned Cursor adapter metadata with the central display registry
label.
- Updated adapter docs and Storybook fixtures to match the new display
names.
- Added focused registry coverage for built-in labels and unknown plugin
suffix behavior.
## Verification
- `pnpm check:tokens`
- `git diff --check origin/master...fix/adapter-display-labels`
- Patch-addition scan for added secrets, private paths, and internal
links: no matches.
- GitHub duplicate search for open adapter-label/local-suffix issues and
PRs; #8910 was identified as the older superseded public PR.
- `pnpm exec vitest run
ui/src/adapters/adapter-display-registry.test.ts`
- `pnpm --filter @paperclipai/ui typecheck`
- Stale-label scan found no remaining user-facing display-label
suffixes; remaining local wording is operational/test terminology such
as adapter ids, docs about running locally, and test descriptions.
## Risks
Low risk. The change is display-label and documentation focused, and
adapter type ids remain unchanged. The main risk is ambiguous gateway
naming, mitigated by keeping explicit gateway labels where variants need
disambiguation.
## Model Used
OpenAI GPT-5 via Codex, tool-enabled coding agent in a local repository
workspace. Context window size is not exposed by this environment.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agent runs can execute inside reusable, runtime-created git worktree
execution workspaces.
> - Those managed worktrees record the expected branch so later
dispatches do not accidentally run an agent in the wrong checkout.
> - Successful run finalization already checked branch coherence, but it
treated every unrecorded branch switch as fatal.
> - A common publishing flow can briefly switch a clean worktree to a
PR/publish branch that points at the same commit as the recorded issue
branch, leaving no divergent work to protect.
> - This pull request keeps the strict finalization guard for unsafe
drift, but lets finalization restore the recorded branch when
same-commit repair is provably safe.
> - The benefit is fewer false failed runs after harmless branch
switches while preserving hard failures for divergent or dirty
worktrees.
## Linked Issues or Issue Description
No public issue exists for this exact finalization failure. Related
public worktree-recovery context: #3087 and #3056, but those address
different worktree realization/reuse recovery paths rather than
successful-run finalization branch repair.
Bug report details:
**What happened?**
When an adapter run succeeded after switching a managed git worktree
from its recorded issue branch to a publish/PR branch, finalization
failed with a managed worktree branch mismatch even when the publish
branch and recorded branch pointed at the same commit and the worktree
was clean.
**Expected behavior**
Finalization should restore the recorded branch only when it can prove
the worktree is clean, registered, and the recorded branch points at the
current `HEAD`. If the actual branch has different commits or unsafe
state, finalization should continue to fail with bounded validation
evidence.
**Steps to reproduce**
1. Create a runtime-managed `git_worktree` execution workspace for an
issue run.
2. During the adapter run, create and check out a new publish branch
without committing new changes.
3. Return adapter success and let heartbeat finalization run.
4. Before this change, finalization records a failed branch check and
fails the run even though the branches point at the same commit.
5. With this change, finalization records the repair operation, restores
the recorded branch, and records a successful finalize row.
6. Repeat with a commit on the publish branch; finalization still fails
because the branch heads differ.
**Paperclip version or commit**
Reproduced against `master` at `bac7307ec`; fixed by this PR at
`64ec605cf`.
**Deployment mode**
Local dev / built from source.
**Agent adapter(s) involved**
Not adapter-specific. This is core heartbeat/workspace finalization
behavior.
**Database mode**
Embedded test Postgres in the focused server test.
**Access context**
Agent run finalization.
**Node.js version**
`v25.6.1`
**Operating system**
`Darwin 24.6.0 arm64`
**Relevant logs or output**
The new focused test intentionally exercises both outcomes:
```text
Test Files 1 passed (1)
Tests 3 passed (3)
```
**Relevant config**
Runtime-created `git_worktree` execution workspace.
**Additional context**
The unsafe divergent branch case still fails with
`workspace_validation_failed` and `git_worktree_branch_incoherence`
evidence.
**Privacy checklist**
Reviewed; this description avoids internal task links, local workspace
paths, credentials, and instance-specific URLs.
## What Changed
- Reused the existing guarded branch-coherence repair helper during
heartbeat finalization when the final branch inspection finds clean
same-commit branch drift.
- Recorded repair metadata in the `workspace_finalize` operation so
reviewers/operators can audit whether finalization repaired branch
drift.
- Preserved failure behavior for divergent branch heads and surfaced the
bounded workspace validation evidence from the repair helper.
- Added focused server coverage for safe finalization repair and unsafe
divergent branch failure.
- Updated execution semantics docs to describe the narrower finalization
rule.
## Verification
- `pnpm exec vitest run
server/src/__tests__/heartbeat-workspace-finalize-branch.test.ts`
- `pnpm --filter @paperclipai/server typecheck`
- `git diff --check`
## Risks
Low to medium risk. The change affects successful-run finalization for
runtime-created git worktree execution workspaces. The repair path is
constrained to clean, registered, same-commit branch drift, and the
focused test confirms divergent branch heads still fail instead of being
restored silently.
## Model Used
OpenAI Codex, GPT-5-based coding agent. Exact hosted model ID was not
exposed in the runtime; tool use and local shell execution were enabled.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agent adapters share managed-runtime helpers from
`@paperclipai/adapter-utils` so local and sandboxed runs can prepare,
execute, and restore workspaces consistently.
> - The sandbox managed runtime syncs workspaces in both directions by
creating tar archives on the local host and inside the remote sandbox.
> - A prior fix avoided archiving `.` during upload because tar
self-entries can force chmod/utime on a directory the command user does
not own.
> - The restore/download path still archived the remote workspace as
`.`, and failed managed commands only surfaced stderr.
> - This pull request applies entry-based tar creation to the sandbox
restore path and includes stdout in managed command failure diagnostics.
> - The benefit is that restore failures become visible to operators and
sandbox workspace restore avoids the same directory-metadata failure
class already fixed for upload.
## Linked Issues or Issue Description
No existing public issue found; describing in-PR (bug).
- **What happens:** sandbox workspace restore can fail while creating
`workspace-download.tar` from the remote workspace when the tar command
includes a `.` self-entry and the command user cannot update metadata on
the workspace directory. If the failing command writes its diagnostic to
stdout, the managed runtime error can collapse to a generic failed shell
command without the useful tar message.
- **Expected behavior:** restore should archive the workspace entries
without a `.` self-entry, and failed managed runtime commands should
include useful stdout/stderr diagnostics.
- **Where:** `packages/adapter-utils/src/sandbox-managed-runtime.ts`
restore/download path and
`packages/adapter-utils/src/command-managed-runtime.ts` command error
formatting.
- **Related public context:** #7836 fixed the upload side of the same
tar self-entry failure class.
## What Changed
- Added stdout-aware failed-command formatting in the command managed
runtime, keeping diagnostics bounded to the tail of stdout/stderr.
- Added remote workspace tarball creation that names top-level entries
explicitly instead of archiving `.` during sandbox restore.
- Preserved empty-workspace restore support by creating a valid empty
tarball when the remote workspace has no entries.
- Added regression coverage for stdout diagnostics, restore tar members,
and empty workspace restore tarballs.
## Verification
- `pnpm vitest run
packages/adapter-utils/src/command-managed-runtime.test.ts
packages/adapter-utils/src/sandbox-managed-runtime.test.ts` — 2 files,
17 tests passed.
- `pnpm --filter @paperclipai/adapter-utils typecheck` — passed.
- `git diff --check origin/master..HEAD` — passed.
- Local public-hygiene/PII scan of the committed diff checked for
internal ticket refs, local/private URLs, common token/key patterns,
private-key blocks, and email-like values — passed.
- GitHub duplicate/related search found no public issue or PR for
`workspace-download.tar Permission denied` or `sandbox restore tar
permission denied`; #7836 is linked as related prior work.
- PR CI on commit `3ad4c8d` — all GitHub Actions lanes, security scans,
and aggregate `verify` passed.
- Greptile Review on commit `3ad4c8d` — Confidence Score 5/5; the prior
P2 thread is resolved with no open P2s, recommendations, or follow-ups.
## Risks
Low. This is limited to shared adapter runtime error formatting and
sandbox restore archive construction. Archive contents should remain
equivalent apart from the removed `.` self-entry, and the new
diagnostics are bounded to avoid dumping unbounded command output.
## Model Used
OpenAI Codex, GPT-5, tool-enabled coding agent with shell and GitHub CLI
access. Context window size was not reported by the runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes (n/a;
internal adapter-runtime behavior only)
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Issue-thread interactions are the subsystem that lets board users
answer structured prompts and resume agent work
> - Checkbox confirmations capture a selected subset of known options,
then wake the assignee through continuation context
> - The wake context previously carried generic interaction metadata,
but not the accepted checkbox option ids or option labels
> - That meant the resumed agent could be woken after a checkbox
confirmation without seeing the board's selected options in the turn
context
> - This pull request carries accepted checkbox selections through the
interaction continuation wake snapshot and renders them into the adapter
wake prompt
> - The benefit is that agents can act on checkbox-confirmation
selections without refetching or guessing the user's choices
## Linked Issues or Issue Description
No public GitHub issue exists for this bug. Searched public issues and
PRs for checkbox confirmation / continuation selection duplicates and
found no matching issue or PR.
### Pre-submission checklist
- [x] I have searched existing open and closed issues and this is not a
duplicate.
- [x] I am on the latest released version of Paperclip or can reproduce
on `master`.
- [x] I have confirmed the error originates in Paperclip itself, not in
my agent adapter, API provider, or local configuration.
### What happened?
When a board user accepted a `request_checkbox_confirmation`
interaction, the assignee continuation wake included generic interaction
metadata but did not include the accepted checkbox selections. The
resumed agent turn therefore had no in-prompt access to the selected
option ids or option labels/descriptions.
### Expected behavior
When a `request_checkbox_confirmation` interaction is accepted, the
resumed agent wake should include the checkbox prompt, selected option
ids, and selected option labels/descriptions so the agent can act on the
selected subset directly.
### Steps to reproduce
1. Create an issue-thread `request_checkbox_confirmation` interaction
with multiple options and `continuationPolicy: "wake_assignee"`.
2. Accept the interaction with one or more selected options.
3. Inspect the continuation wake payload/prompt received by the
assignee.
4. Observe that the selected checkbox options are missing from the wake
context before this fix.
### Paperclip version or commit
Reproduced against the pre-fix code path on `master`; this PR head is
`9d17e70bce373e4850117f30c015c973c4b61789`.
### Deployment mode
Local dev (pnpm dev) / built from source.
### Installation method
Built from source (pnpm dev / pnpm build).
### Agent adapter(s) involved
Not adapter-specific (core bug). The Codex/local adapter path exposed
the missing wake context, but the missing field was in core interaction
continuation payload construction.
### Database mode
Embedded PGlite or external Postgres; the bug is not database-mode
specific.
### Access context
Both. Board users resolve the checkbox interaction, and agent bearer-key
wakes consume the continuation context.
### Node.js version
`v22.22.2`
### Operating system
Linux workspace.
### Relevant logs or output
No runtime exception is required to reproduce this. The failure mode is
missing `checkboxSelection` data in the resolved interaction
continuation wake payload.
### Relevant config
Not config-related.
### Additional context
Root cause: accepted checkbox interaction results were not extracted
into the continuation wake context, and adapter wake payload
normalization/rendering had no typed `checkboxSelection` field.
### Privacy checklist
- [x] I have reviewed all pasted output for PII (usernames, file paths,
API keys, tokens, company names) and redacted where necessary.
## What Changed
- Added checkbox selection extraction for accepted
`request_checkbox_confirmation` interactions and stored it in
interaction continuation wake context.
- Included checkbox selection context in heartbeat wake payload
construction.
- Added adapter-utils normalization and wake prompt rendering for
checkbox prompt, selected ids, and selected option details.
- Added regression coverage for route continuation context, heartbeat
payload summaries, and adapter wake prompt rendering.
## Verification
- `pnpm exec vitest run packages/adapter-utils/src/server-utils.test.ts
server/src/__tests__/heartbeat-context-summary.test.ts
server/src/__tests__/issue-thread-interaction-routes.test.ts`
- `git diff --check origin/master...HEAD`
- `rg -n "checkbox|confirmation|interaction|wake|continuation"
ROADMAP.md`
- `gh pr list --state all --search "checkbox continuation selection
repo:paperclipai/paperclip" --json number,title,state,url,headRefName
--limit 20`
- `gh issue list --state all --search "checkbox confirmation options
repo:paperclipai/paperclip" --json number,title,state,url --limit 20`
## Risks
Low risk. The new payload field is additive, only populated for accepted
checkbox confirmations, and existing continuation fields are preserved.
The main compatibility risk is downstream code assuming an exact wake
payload shape; adapter normalization treats the new field as optional.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex coding agent based on GPT-5, with shell/tool execution in
this workspace.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Return blockedBy and blocks relation summaries from issue create paths after blocker relations are synced. Refresh child relation summaries after blockParentUntilDone adds a parent blocker relation.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The app shell exposes user-visible product surfaces through routes
and the left navigation
> - The Work Timeline frontend landed on `master` in related PR #8880
before the product surface was ready for general users
> - The backend aggregation endpoint and shared DTOs can remain
available for continued iteration without exposing the page in the main
app
> - This pull request removes the visible `/timeline` route, sidebar
entry, page implementation, chart component, and Storybook fixtures
> - The benefit is that users no longer see an unfinished Work Timeline
page on `master`, while future work can continue from a preserved
branch/workspace
## Linked Issues or Issue Description
No public GitHub issue exists for this rollback request.
Bug-style description:
- **What happened:** A Work Timeline page was exposed in the app
navigation before the surface was ready for users.
- **Expected behavior:** Unready product work should not be visible from
the default app shell on `master`.
- **Steps to reproduce:** Open the app on current `master`; the sidebar
includes a `Timeline` item that routes to `/timeline`.
- **Paperclip version/commit:**
`60f7fb422394c94618b8eef27ae032702004f544`.
- **Deployment mode:** Local app / standard Paperclip app shell.
- **Related public PR:** #8880.
## What Changed
- Removed the `/timeline` route and `Timeline` page import from the app
route table.
- Removed the `Timeline` sidebar item and unused `GanttChartSquare` icon
import.
- Deleted the frontend Work Timeline API wrapper, chart component,
layout helper, page, Storybook story, and sample fixtures.
- Removed the now-unused `queryKeys.workTimeline` entry.
- Left the backend timeline endpoint and shared DTOs intact so the data
contract can continue to be developed off the preserved work.
## Verification
- `pnpm --filter @paperclipai/ui typecheck`
- Searched the frontend for stale `workTimeline`, `WorkTimeline`,
`/timeline` route/sidebar, and `GanttChartSquare` references after
deletion.
## Risks
- Low runtime risk: this removes an app route and navigation entry for
an unfinished surface.
- Deep links to `/timeline` will now fall through to the app's existing
not-found behavior.
- The backend endpoint remains available; if the intent was to remove
the API too, that should be handled in a separate, explicit PR.
## Model Used
OpenAI Codex coding agent, GPT-5-based model, with shell/tool use for
repository inspection, code editing, git, and GitHub CLI operations.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge
Co-authored-by: Paperclip <noreply@paperclip.ing>
Adds the public telemetry data contract README, links it from contributor docs, and adds a focused README contract test for generated helper names.
Verification:
- git diff --check origin/master..HEAD
- pnpm exec vitest run packages/shared/src/telemetry/readme-contract.test.ts
- PR CI green
- Greptile 5/5
Co-Authored-By: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Operators need to *see* how work actually flowed across their agents
over time — who was invoked, what they worked on, and how work was
delegated between them
> - The dashboard shows point-in-time state but nothing reconstructs the
temporal, cross-actor picture of heartbeat runs and delegations
> - A read-only company work-timeline endpoint was landed first (server
aggregation over runs/issues/activity); it had no frontend
> - This pull request adds the Gantt-style **Work Timeline** page that
renders that endpoint, plus the small additive server contract change it
needs (shared DTOs + a task title on each span)
> - The benefit is a single dense view — actor rows, concurrency lanes,
delegation connectors, zoom and a mini-map — that makes agent activity
legible without an N+1 fetch storm from the client
## Linked Issues or Issue Description
No public GitHub issue. Problem, in-PR:
- **Gap:** the company work-timeline aggregation endpoint has no UI.
There is no way to visually inspect how heartbeat runs unfolded over
time or how work was delegated between agents.
- **Solution:** a dashboard-adjacent Gantt-style page at
`/:companyPrefix/timeline`, linked from the sidebar's "Work" section,
rendering runs as bars on per-actor rows with delegation connectors,
kickoff chips, zoom, a lens filter, and a mini-map.
- Built with React + custom inline SVG (no chart dependency; consistent
with the existing Tailwind/Radix stack).
## What Changed
- **Frontend Gantt page** (`ui/src/pages/Timeline.tsx`,
`ui/src/components/timeline/WorkTimelineChart.tsx`): actor rows
(agents/system only — humans never get a row), overlapping runs packed
into concurrency sub-lanes, bars = heartbeat runs with a left colour tab
for issue identity, truncated task title + timing/status on hover,
click-through to the task.
- **Human activity markers & human rows** for kickoff/delegation
involving people, without giving humans their own run lane.
- **Kickoff avatar chips** at each bar's leading edge; straight
agent→agent delegation connectors (dashed for
retries/changes-requested); in-progress runs extend to a dashed "now"
line and fade out.
- **Zoom** (hour/day/week, auto-fit), full-window **mini-map** with a
draggable brush, **lens filter** (Everyone / per-user, server-side), and
colour **by task / by status**.
- **Pure layout/transform module** (`ui/src/lib/timeline/layout.ts`) —
packing, kickoff derivation, connector resolution, scales — unit-tested
in isolation.
- **Server contract (additive):** moved the `WorkTimeline*` DTOs into
`@paperclipai/shared` so the aggregation service and the UI consume one
contract; added `issueTitle` to each span so the tooltip shows the task
title with no N+1 client fetch.
- Sidebar link, query keys, API client (`ui/src/api/workTimeline.ts`),
and a Storybook story with fixtures.
## Verification
- `pnpm --filter @paperclipai/shared build` ✅
- `pnpm --filter @paperclipai/server typecheck` ✅ · `pnpm --filter
@paperclipai/ui typecheck` ✅
- `pnpm --filter @paperclipai/ui exec vitest run
src/lib/timeline/layout.test.ts
src/components/timeline/WorkTimelineChart.test.tsx` ✅ (15/15)
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/work-timeline-service.test.ts` ✅ (5/5) — the DTO move +
`issueTitle` are additive; existing service tests use `objectContaining`
and still pass.
- Rendered `WorkTimelineChart` headless against a real slice of company
activity via a Storybook story; manual browser QA of the live page
passed on the feature branch.
## Risks
- **Low risk.** The change is UI-only plus an additive server DTO
refactor (types relocated to `@paperclipai/shared`, one new optional
field). No schema/migration changes, no change to endpoint behaviour
beyond the extra `issueTitle` field. The page is behind its own route
and does not alter existing views.
## Model Used
- Claude, Opus 4.8 (`claude-opus-4-8`), via Claude Code with extended
thinking and tool use.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above (only the merged endpoint PR #8875 is related; no duplicates)
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change and contains no internal
ticket id
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Operators need visibility into who initiated work, which agents ran,
and how tasks were delegated across a company.
> - The existing control plane stores the raw data across issues,
heartbeat runs, comments, approvals, interactions, and activity logs.
> - There was no single company-scoped API response that reconstructed
those records into timeline actors, spans, events, and edges for a
Gantt-style view.
> - This pull request adds that aggregation endpoint behind the same
company and issue read authorization model used elsewhere.
> - The benefit is that UI work can consume one bounded endpoint instead
of reimplementing timeline joins client-side.
## Linked Issues or Issue Description
No public GitHub issue exists for this feature.
## Problem or motivation
Paperclip stores enough execution and delegation data to show work over
time, but consumers need a single endpoint that aggregates it
consistently.
## Proposed solution
Add `GET /api/companies/:companyId/timeline` with date and entity
filters, bounded windows, pagination, actor normalization, run spans,
human events, and delegation/assignment edges.
## Alternatives considered
Querying each source separately from the UI would duplicate ACL and
attribution logic and make client rendering depend on storage details.
## Roadmap alignment
This supports operator visibility and auditability, and does not
duplicate a listed roadmap item.
## What Changed
- Added a `workTimelineService` that aggregates issue candidates from
runs, activity, comments, approvals, interactions, and recently touched
issues.
- Added `GET /api/companies/:companyId/timeline` with `from`, `to`,
`userId`, `goalId`, `projectId`, `issueId`, `limit`, and `offset` query
parameters.
- Enforced company-scope access plus per-issue `issue:read` filtering
before emitting spans, events, or edges.
- Added 31-day window capping, in-progress span handling for null
`finishedAt`, retry/continuation metadata, user-lens subtree filtering,
and activity-log run attribution fallback.
- Added embedded-Postgres tests for aggregation joins, route behavior,
ACL filtering, window capping, and user-lens closure.
## Verification
- `pnpm vitest run server/src/__tests__/work-timeline-service.test.ts`
- `pnpm exec tsc -p server/tsconfig.json --noEmit`
Additional smoke attempted:
- `pnpm dev:once` did not start the local app because the existing
embedded instance has pending migration drift: Postgres rejected a
foreign key on `pipeline_case_blockers.company_id` because that column
does not exist. I did not manually alter the embedded database.
## Risks
- Medium risk: this introduces a new aggregate endpoint over several
tables, so query volume should be watched on very large companies.
- The endpoint caps windows and paginates issue candidates to keep the
first version bounded.
- ACL behavior is fail-closed per issue: unreadable issues are filtered
before response rows are emitted.
- No migrations or schema changes are included.
## Model Used
OpenAI GPT-5 via Codex coding agent, with tool use for repository
inspection, editing, local Vitest execution, TypeScript checking, git,
and GitHub CLI operations.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
Add check-pr skill guidance that requires a fresh, clean Greptile review against the current PR or MR head before treating a review handoff as ready.
This updates the GitHub and GitLab reference paths with concrete current-head checks and explicit blocking behavior for stale, missing, or failed Greptile results.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Dotta
Nicky Leach
sparkeros
Evyatar Bluzer
Mikes
neerajdad123-byte
fengqing
Devin Foley
github-actions[bot]
