Commit Graph
8312 Commits
Author SHA1 Message Date
Nicky LeachandPaperclip 8af66f48e9 Admit explicit queued steering with durable acknowledgement in wake-queue (#22276)
## Thinking Path

> - A board user can send a queued message into an active agent turn.
> - The server must know which queue, issue and run the user selected.
> - A provider can accept a message even when the client loses the HTTP
response.
> - The route previously handled authorization, replay, delivery,
database writes and response construction in one block.
> - Wake-queue can own the steering operation and its acknowledgement
while the route keeps the board access decision.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Explicit same-turn delivery of a queued board comment or interaction.

**Subsystem affected**

Server task admission.

**Current behavior**

The issue route issues SQL, interprets the provider acknowledgement and
updates the wake, run and identity.

**Proposed behavior**

The route calls one steering command. The command decides replay, checks
the revision and the selected entry, and leaves an uncertain delivery
pending. The adapter handles identity reservation, the issue and wake
locks, and persistence after acknowledgement.

**Additional context**

Builds on the board queue extraction. Related earlier work in #13160
locked the target run while waiting for a provider. Today's runner
writes its acknowledgement to that row.

## What Changed

- Use the shared board queue read and lock for pending messages and
acknowledgement replay.
- Keep the target run available while waiting for the provider. Re-read
and lock the scoped run after acknowledgement and preserve concurrent
result updates.
- Leave HTTP access, activity logging, response redaction and error
translation with the route.

## Verification

On a3d18b1b66, the full route and mutation suites passed 162 tests
together with the repository Postgres runner. An independent route-only
run passed all 145 assertions and timed out cleaning up the database.
Eleven focused checks passed, including the final interrupt audit
assertion. Server typecheck and module boundaries passed.

Run the queued-comment route suite and the wake-queue application tests.
Exercise exact replay, concurrent acknowledgement writes, stopped
targets, fresh-session approvals, permission checks, definite rejection
and an uncertain timeout.

## Risks

A wrong acknowledgement decision could consume a message twice or drop
an undelivered message. The transaction checks the company, issue, agent
and run and merges the latest result before consuming the queue entry.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:40 -08:00
Nicky LeachandPaperclip d23a690cdf refactor: share the board queue snapshot and lock in wake-queue (#22273)
## Thinking Path

> - Paperclip users can inspect queued messages, interrupt a task, or
steer the active run.
> - All three operations need the same view of pending comments,
approvals and first-turn inputs.
> - The HTTP routes owned the code that loaded and locked this state.
> - A separate move makes the later steering transaction easier to
review.
> - The same callers now use the board queue reader and lock in
wake-queue.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Reading the board queue and locking its current state for Interrupt and
Steer.

**Subsystem affected**

Server task admission.

**Current behavior**

Local functions in the issue route select the ordered queue and apply
its locking rules.

**Proposed behavior**

The existing route handlers call the same implementation through the
wake-queue boundary.

**Additional context**

Depends on #22272. This supplies the current board view for the steering
extraction discussed in #13160.

## What Changed

- Move the existing board snapshot and lock into a Postgres adapter.
- Use the shared reader from GET, Interrupt and Steer, including
acknowledgement replay.

## Verification

Fifteen focused Postgres route tests passed on the extracted
implementation. They cover live queue reads, Interrupt, acknowledgement
replay, concurrent run updates, stale targets and timeouts. Run `pnpm
exec vitest run
server/src/__tests__/issue-queued-comments-routes.test.ts` and `node
scripts/check-module-boundaries.mjs`. Review the move with `git diff
--color-moved`.

## Risks

A change to these shared reads could affect which messages users see or
whether a pending input can be interrupted. The move preserves the
queries, lock order, rich interaction entries and caller-specific live
probe behavior.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:40 -08:00
Nicky LeachandPaperclip ebb98120dc Own the issue admission lock and dispatch after commit in wake-queue (#22272)
## Thinking Path

> - Paperclip admits work for a task while other agents and users may
also act on it.
> - A fresh run and a wake behind an active execution both require the
same issue lock.
> - Heartbeat previously opened that transaction and passed handles
across the module boundary.
> - The wake-queue module can bind both admission operations to the
locked company and issue.
> - The result of the database commit determines whether to emit a
queued event, dispatch a run, or return a saved result.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The transaction and handoff used by task-bound wake admission.

**Subsystem affected**

Server task admission.

**Current behavior**

Heartbeat opens the transaction, builds a scope for the busy path, and
dispatches based on the result. Its contention handler can reach
buffered side effects after a rollback.

**Proposed behavior**

Wake-queue owns the lock and the durable acknowledgement. The
application hands off a committed result. A rolled-back contention
attempt returns without publishing its buffered effects.

**Additional context**

Depends on #22268 and #22266.

## What Changed

- Bind the busy and fresh admission operations to a single company and
issue in Postgres. Remove the transaction scope object.
- Keep specialized heartbeat gates and continuation writes on the
acquired transaction.
- Buffer the workspace preflight activity publication until the
transaction commits.
- Centralize the handoff for new, coalesced, replayed, deferred, skipped
and durable results.

## Verification

On 1c5a069406, local qualification passed 94 application tests, 33
focused Postgres scenarios, and all four fresh/busy rollback cases.
Server typecheck and the module boundary check passed.

Run the wake-queue application and adapter tests and the heartbeat queue
and comment wake suites. Verify the rollback, replay, chat
acknowledgement, and tenant and issue mismatch cases. Run the server
typecheck and module boundary check.

## Risks

The ordering of commit, saved notification and dispatch is observable. A
recognized chat authorization contention now discards buffered effects
from the rolled-back transaction. Specialized heartbeat policy still
uses the locked database transaction.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:40 -08:00
Nicky LeachandPaperclip eca7f85778 Admit saved task comments with the fresh issue run (#22268)
## Thinking Path

> - Paperclip agents take work from assigned tasks and from user
comments.
> - A fresh task run can include saved comments when the current agent
or a confirmed former assignee owns them.
> - Connected chat messages and resolved interactions have separate
authority and session requirements.
> - Heartbeat previously decided which receipts to adopt between the
three calls that saved a new run.
> - One wake-queue use case now selects the receipts and commits the
same run and comment lineage.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Assignment and comment continuation when a task needs a fresh run.

**Subsystem affected**

Server task admission.

**Current behavior**

Heartbeat chooses the comment receipts to consume, reads their source,
and builds the final run context.

**Proposed behavior**

One application operation admits the run. Its Postgres adapter loads
eligible company and agent receipts under the issue lock. The caller
supplies the responsible user and records the specialized continuation.

**Additional context**

Builds on #22266. The existing release and queued-comment boundaries are
in #13136 and #13145.

## What Changed

- Keep exact resumed receipts separate from ordinary board comments.
Adopt a prior assignee’s comments only when the interrupted run proves a
handoff.
- Use the same canonical comment ID codecs for admission and dispatch.
- Test the assignment path with one or two saved comments and
independent chat and interaction receipts.

## Verification

On c957f8529c, 260 tests passed across the four admission, liveness and
responsible-user suites. The saved Grok interrupt route passed its
exactly-once continuation test. A separate Postgres run passed the
ordered comment and rollback checks, both reassignment cases, and the
company isolation test. Server typecheck and module boundaries passed.

Check the fresh admission and handoff cases in
`server/src/services/heartbeat/queue.test.ts`. Run `pnpm exec vitest run
server/src/__tests__/heartbeat-comment-wake-batching.test.ts
server/src/services/issue-queued-comment-queue.test.ts`, `pnpm --filter
@paperclipai/server typecheck`, and `node
scripts/check-module-boundaries.mjs`.

## Risks

Receipt selection controls which user input reaches the next agent. The
store requires the same company, issue and executor or a verified
handoff. Chat and interaction receipts preserve their independent
delivery.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:39 -08:00
Nicky LeachandPaperclip f324238f73 Move fresh issue run and receipt writes into wake-queue (#22266)
## Thinking Path

> - Paperclip manages AI agents at work.
> - Assigning a task or resuming it from a comment can create a queued
run.
> - The wake-queue module handles admission behind an active execution.
Heartbeat also writes the receipt and run when a new execution is
needed.
> - These writes share the issue lock. Splitting them across
transactions would allow duplicate or partially bound work.
> - This change puts the fresh writes in the wake-queue module under the
existing lock.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Creating a queued run for an assigned or continued task.

**Subsystem affected**

Server task admission.

**Current behavior**

Heartbeat constructs the receipt and run, handles retry lineage, and
ties adopted receipts to the run.

**Proposed behavior**

Wake-queue owns receipt promotion, fresh-run construction, and receipt
binding. Heartbeat still selects saved comments and orders recovery
effects inside the same transaction.

**Additional context**

Earlier module boundaries were introduced in #13136 and #13145.

## What Changed

- Move fresh receipt, run, and binding writes to a transaction-bound
Postgres adapter.
- Keep explicit continuation and reconciled retry lineage in the
application layer.
- Scope receipt updates by company and durable promotion by agent. Cover
both predicates with a database test.

## Verification

On commit 7479acbd22, all 104 heartbeat queue tests passed using the
repository Postgres command runner. All 297 assertions passed in the
six-file sweep. The standalone cluster cleanup timeout also reproduced
on pristine base 92dbf39e6f after all 103 base tests passed.

`node cli/node_modules/tsx/dist/cli.mjs
packages/db/src/test-postgres-command.ts -- node
node_modules/vitest/vitest.mjs run
server/src/services/heartbeat/queue.test.ts`

Run `pnpm exec vitest run server/src/services/heartbeat/queue.test.ts
server/src/__tests__/heartbeat-comment-wake-batching.test.ts
server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts`. Run
`pnpm --filter @paperclipai/server typecheck` and `node
scripts/check-module-boundaries.mjs`.

## Risks

Changing write order can attach the wrong receipt or lose retry lineage.
The caller retains the transaction and the interleaved chat and recovery
effects. This is a structural change. No latency improvement is claimed.

## Model Used

OpenAI GPT-6.2 Sol (`gpt-6.2-sol`) implemented the change. OpenAI Codex
directed the work, reviewed the diff, and ran qualification.

## 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>
2026-11-18 19:24:39 -08:00
1dba97303e fix(runner): wait for run.attach before restoring a Codex session on a fresh Runner (#22267)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Runnerd runs a coding harness such as Codex or Claude (through ACPX)
for one agent session, and keeps durable state so a later run can
continue the conversation
> - Core can rotate a session to a new run before it starts the Runner.
It archives the old Runner state and starts a Runner under the new run's
identity, over the same saved provider session
> - ACPX waits for `run.attach` in this case. Codex does not: if the
saved session was still open, Codex restores the app server on the first
poll or command, with the old run's settings
> - This pull request makes Codex follow the ACPX rule
> - The benefit is one app-server start with the new run's settings, and
no old-session events in the new run before attachment

## Linked Issues or Issue Description

**What existing behavior does this improve?**

A Runner that starts with fresh durable state over a saved, open Codex
session.

**Subsystem affected**

Runnerd: the durable runner and the Codex provider executor.

**Current behavior**

The Codex executor restores the app server on the first poll or command.
It uses the saved run's tools and settings. Restore events go out under
the new run before `run.attach`. If `run.attach` changes the tool set,
the app server restarts, so it starts twice.

**Proposed behavior**

The Codex executor waits for `run.attach` before it restores. Until then
it refuses commands that start work; snapshots and shutdown commands
still work. The wait is saved with the Codex state, so a restart before
attachment keeps it. `run.attach` treats the saved open session like a
stopped session, so the app server starts once with the new run's
settings. A Runner that recovers its own durable state restores as
before.

**Reason and benefit**

All providers then use one rule for a Runner that starts as a new run.
Today this case occurs only after a rotation from a lost Runner or from
a session left open. A later change can use the same rotation for every
follow-up that starts a new Runner process.

## What Changed

- Before it creates fresh durable state, the durable runner tells the
executor (`observe_fresh_durable_state`).
- The native executor then marks a saved Codex session as waiting for
`run.attach`. The Codex executor reads the mark when it loads the
session.
- The Codex executor does not restore the provider until attachment, and
refuses commands that start work. Snapshot, close, drain, suspend,
shutdown, interrupt, cancel and stop still pass.
- The mark (`awaitingRunAttach`) is saved before the Runner's durable
state exists, so a Runner lost or restarted before `run.attach` keeps
waiting. `run.attach` clears it. `run.attach` accepts a saved
`session_open` or `provider_exited` session without a live provider, the
same as a stopped (`prepared`) session.
- `DURABLE_TRANSPORT.md` describes the rule.
- Four tests: a fresh Runner waits for `run.attach` and starts Codex
once; a restart before attachment still waits; a Runner lost right after
a fresh start still waits; a recovered Runner still restores its own
session.

## Verification

- `cargo test -p paperclip-runner-core --test codex_provider --test
native_provider_backend --test durable_recovery`: 131, 47 and 4 passed.
- `npx vitest run src/live/runnerd-codex-transport.test.ts` in
`packages/paperclip-runner`, with a rebuilt runnerd: 335 passed,
including the removed-context rotation.
- `cargo test -p paperclip-runner-core --lib durable::`: 133 passed.
- Red-green: with the fence turned off,
`a_fresh_runner_waits_for_run_attach_before_restoring_a_saved_session`
fails on the first poll. Without the saved wait,
`a_fresh_runner_restarted_before_run_attach_still_waits_for_it` fails.
- `cargo fmt --all -- --check` passes.

## Risks

- Low risk. The fence applies only when the durable state is fresh and a
saved Codex session exists. New sessions have no saved session.
Recovered Runners do not get the fence.
- While the fence is set, the Runner refuses commands that start work.
Core sends `run.attach` first after a rotation, so no current flow is
blocked. Teardown commands still pass, so a session whose `run.attach`
fails can still close.
- The new state field is omitted when false, and older Runners ignore
it.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use
(code search, editing, local test runs).

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1119.0-canary.830700
2026-11-18 19:23:02 -08:00
DottaandClaude Opus 5.5 12fc89b1f7 fix(cloud): let an online move proceed when Cloud supplies the database listener (#22263)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Hosted Paperclip servers can move from a server with a volume to a
volume-free server, which allows deploys without downtime
> - Before the move, Core checks that the volume-free configuration is
complete
> - That check requires `PAPERCLIP_DATABASE_LISTEN_URL` on the running
volume server, but only the volume-free replacement uses it, and Cloud
supplies it when it configures that replacement
> - Many older servers never had the setting, so they cannot move online
even when all their data is ready
> - This pull request stops an unset listener from blocking, and keeps a
listener that points at another database as a blocker
> - The benefit is that older servers can move online

## Linked Issues or Issue Description

**What existing behavior does this improve?**
The online move refuses a volume server that has no
`PAPERCLIP_DATABASE_LISTEN_URL`.

**Subsystem affected**
Server: ephemeral enrollment readiness
(`server/src/services/ephemeral-enrollment.ts`).

**Current behavior**
The eligibility read and preparation report
`volume_free_database_listener_required` for every server that has no
listener setting.

**Proposed behavior**
An unset listener does not block. A listener that does not match the
runtime database still blocks with the same name.

**Reason and benefit**
The replacement server receives the listener from Cloud. On staging,
this check alone blocks 18 servers whose data is otherwise ready.

**Breaking changes**
None. The startup contract for a running volume-free server is
unchanged.

## What Changed

- `services/ephemeral-enrollment.ts`: when the only configuration
failure is the listener, and the listener is unset, the readiness check
passes. The listener check is the last check in
`assertEphemeralServerConfig`, so all earlier settings were already
valid.
- `services/ephemeral-enrollment.test.ts`: tests for an unset listener
(eligible, and preparation succeeds) and a mismatched listener (still
blocked).

## Verification

- `npx vitest run src/services/ephemeral-enrollment.test.ts
src/routes/ephemeral-enrollment.test.ts`: 29/29 pass.

## Risks

- Low. Cloud's online arming passes `PAPERCLIP_DATABASE_LISTEN_URL` with
the replacement's variables. If the replacement did not get the setting,
the existing startup contract would still refuse to boot it, and the
move would not complete.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, browser).

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1119.0-canary.830600
2026-11-18 20:39:56 -06:00
Devin FoleyandPaperclip 3dffb2c9dd Fix project sidebar navigation and pinned task expansion (#22264)
Open recent and pinned projects on Tasks and share their expandable task list.
Keep project pin and reorder controls at the header. Preserve unread markers
and monitoring status through the existing full issue response.

Verified 82 focused tests, UI typecheck, production build, token gates,
and 58 successful CI checks. Greptile is 5/5 with all threads resolved.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
canary/v2026.1119.0-canary.830500
2026-11-18 17:38:38 -08:00
DottaandClaude Opus 5.5 9b16044bf1 fix(cloud): move idle local workspaces in the online durable-data pass (#22270)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A hosted server can move to volume-free storage only when no durable
data stays on its local volume
> - The online durable-data pass moves that data while the server keeps
serving, one bounded and resumable pass at a time
> - The pass does not move local execution workspaces, so servers with
local workspaces stay ineligible (`workspaces_require_migration`)
> - Online-safe owners for workspaces already exist: the online remote
workspace migration and the online workspace operation reconciliation
> - This pull request adds workspace phases to the pass that call those
owners, and defers busy or unsupported workspaces with a reason
> - The benefit is that idle workspaces move with no outage, and
operators can see which workspaces cannot move and why

## Linked Issues or Issue Description

**What happened?**
The online durable-data pass never moves local execution workspaces. A
server with local workspaces keeps the `workspaces_require_migration`
blocker after every pass.

**Expected behavior**
The pass moves each idle local workspace to shared storage through the
online owner. It defers a busy or unsupported workspace and reports the
reason.

**Steps to reproduce**
1. Run the online durable-data pass on a server that has a local
`local_fs` execution workspace.
2. Read the pass result and the eligibility blockers.
3. The workspace stays local and `workspaces_require_migration` stays.

**Deployment mode**
Hosted server that moves from a local volume to volume-free storage.

## What Changed

- Add two phases to the online durable-data pass, after
`runtime_skill_assets` and before the native phases:
- `workspace_operations`: pages companies that have local workspaces and
calls `reconcileOnlineWorkspaceOperations` for each. It counts
`workspaceOperations` and defers each held operation as
`workspace_operations:<reason>`.
- `workspaces`: pages local workspaces (same filter as the eligibility
check), deepest path first so nested workspaces go before their parents.
For each workspace it reads `inventoryRemoteWorkspaceMigration`. If the
workspace is eligible, it calls `migrateRemoteWorkspace` in online mode
(never `writersStopped`) with the pass signal and a 1 s source-lock
wait.
- A workspace that the owner refuses is deferred with each owner reason
as `workspaces:<reason>`, for example `workspaces:active_execution`,
`workspaces:task_binding_required`,
`workspaces:workspace_provider_unsupported`,
`workspaces:workspace_source_busy`, or `workspaces:execution_rows_busy`.
An unknown error becomes `workspaces:owner_failed` and its message is
not echoed. The page continues with the next workspace.
- Both phases use a cursor and a limit that the pass can halve after a
budget timeout, like the other phases.
- Add `listLocalWorkspaceCompanies` and `listLocalWorkspaces` next to
`localWorkspaceDependencyWhere`.
- The pass stops waiting for a workspace owner at the budget. It reports
`workspaces:owner_busy` until that owner settles.

## Verification

- `cd server && npx vitest run
src/services/online-durable-data-migration.test.ts
src/services/online-durable-data-migration-postgres.test.ts`
- Unit tests with injected owners: phase order, online mode and lock
wait, deferral codes, owner refusal under locks, cursor resume across
budget-limited calls, and page halving that keeps finished workspaces.
Seven tests fail without the change and pass with it.
- Embedded PostgreSQL test with the real owners: an idle managed-project
workspace moves to a committed snapshot and its files restore from it. A
workspace with a running task run is deferred as
`workspaces:active_execution`, and its record, files, and operations
stay unchanged. The test fails without the change and passes with it.
- Embedded PostgreSQL test for the workspace and company cursors: ten
workspaces in two companies, with equal and different path lengths,
across pages of three. Each workspace appears once, deepest first.
- `pnpm verify` selected 2934 of 3802 test files (almost the full
suite). It was not run to the end. Required CI covers the full suite.

## Risks

- A workspace move that takes longer than one pass budget (60 s) stops
at the budget. The workspace keeps its in-progress move marker, so new
runs for that workspace are refused until a later pass resumes the move.
The pass resumes the same page on the next call. If one workspace times
out twice at page size 1, the pass reports `workspaces:stalled` and goes
on; the next cycle resumes it again. A very large workspace can
therefore stay blocked for runs across passes. The operator online
workspace tool can resume it with a longer deadline.
- A workspace with no proven online source uses the owner's lifecycle
lock, which waits without a timeout. The pass does not wait for it past
the budget. The pass returns at the budget, and the owner stops at its
next abort check after it gets the lock. Until that owner settles, later
passes skip the workspace phase and report `workspaces:owner_busy`, so
two moves never run at the same time.
- Workspaces that can never move online (for example unsupported
providers or workspaces without a task binding) are reported each pass
and are not changed. This change makes no product decision for them.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), via Claude Code with tool use and
code 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
- [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: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 19:35:56 -06:00
DottaandClaude Opus 5.5 067f7a0815 feat(telemetry): send product lifecycle events and agent run failure cause (#22250)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - First-party telemetry tells the team which product steps people
finish
> - Telemetry did not record when a model is connected, when a task is
created, completed, or blocked, when a plan is created or approved, or
when an artifact is created
> - Telemetry also did not tell why an agent run failed, so failures
could not be grouped by cause
> - This pull request syncs the new telemetry contract and sends these
events from the server once per real change
> - The benefit is a product funnel and a failure breakdown that use
only enums, booleans, and counts

## Linked Issues or Issue Description

**Subsystem affected**
Server telemetry (`packages/shared/src/telemetry`,
`server/src/services/product-telemetry.ts`) and the emit sites in the
issue, document, work product, interaction, and AI connection services.

**Problem or motivation**
The team cannot measure the main product path. There is no event for a
new model connection, a new task, a completed task, a blocked task, a
new plan, an approved plan, or a new artifact. `agent.task_run` tells
that a run failed, but not why. The signup funnel also must know when
the onboarding wizard created the first task.

**Proposed solution**
Register the events in the telemetry backend. Sync the generated
contract here. Add typed helpers. Send each event once, after the
transaction that makes the change commits. Use fixed enums for every
kind, reason, and cause.

**Alternatives considered**
A post-commit action queue on the issue service only. The native status
path and many other callers use an external transaction without that
queue, so most agent completions would not send an event. A generic
after-commit hook on the database client covers every caller.

**Roadmap alignment**
This is telemetry for existing features. It adds no new product feature.

**Additional context**
This change depends on paperclipai/telemetry-backend#150, which is
merged. Deploy that backend change before this change ships. Until then,
the collector rejects the new event names.

## What Changed

- Sync `generated/paperclip-telemetry.ts` from the backend branch as a
direct copy. Regenerate `posthog-direct/enum-fallbacks.generated.ts`
with `scripts/generate-posthog-direct-fixtures.mjs`. The loader golden
file did not change.
- Add `afterTransactionCommit()` to `@paperclipai/db`. It runs a
callback after the outermost transaction commits. It drops the callback
on rollback. Outside a transaction it runs the callback at once. A
callback that throws never fails the committed work.
- Add helpers `trackModelConnected`, `trackTaskCreated`,
`trackTaskCompleted`, `trackTaskBlocked`, `trackPlanCreated`,
`trackPlanApproved`, and `trackArtifactCreated`. Add `failureCause` to
`trackAgentTaskRun`. Assign the new events to `operational_enum_count`
retention.
- Add `server/src/services/product-telemetry.ts`. It sends each event
after commit inside `withTelemetryCompany()`, so Cloud direct delivery
gets `company_id` for background writes.
- Emit sites:
- `model.connected`: `aiConnectionService.save`, for a new connection
only. A reconnect sends nothing. `first_for_company` is true when the
company had no earlier model connection.
- `task.created`: `issueService.create`, after the insert. A
deduplicated create, a company import, and a chat conversation send
nothing. `created_by_kind` is `routine` for routine runs, `onboarding`
for the onboarding wizard's first task, and otherwise `user`, `agent`,
or `system`.
- `task.completed` and `task.blocked`: `issueService.update`, when the
status changes to `done` or `blocked`. The same status again sends
nothing.
- `plan.created`: `documentService.upsertIssueDocument`, for the first
revision of the `plan` document.
- `plan.approved`: the accept path of a `request_confirmation` that
targets the task's `plan` document.
- `artifact.created`: `workProductService.createForIssue` (`direct`),
the promotion route (`promotion`), and a run file deliverable
(`run_deliverable`).
- `agent.task_run.failure_cause`: `emitAgentTaskRun`, for `failed`,
`timed_out`, and `interrupted` runs only.
- `blocked_reason` mapping: unfinished blocking tasks give
`waiting_on_task`. Otherwise an unblock owner of a person or the board
gives `waiting_for_person`, and an agent owner gives
`waiting_for_agent`. A system write with neither gives `needs_recovery`.
A person or agent write with neither gives `unspecified`.
- `failure_cause` mapping (stored `errorCode`, with
`resultJson.providerFailure.category` for generic provider and adapter
codes):
- `missing_access`: auth and permission codes (`acpx_auth_required`,
`provider_auth_failed`, `user_secret_missing`, `github_access_denied`,
`github_repo_not_accessible`, `permission_denied`,
`project_access_denied`, `configuration_incomplete`,
`connection_unavailable`, `signing_secret_unconfigured`), and provider
category `authentication` or `permission`.
- `provider_limit`: `provider_quota`, `native_provider_usage_limit`,
`native_provider_overloaded`, `github_rate_limited`,
`ai_connection_busy`, and provider category `rate_limit`,
`quota_exhausted`, or `overloaded`.
- `provider_error`: `native_provider_model_rejected`,
`provider_transport_failed`, `codex_transient_upstream`,
`provider_failed`, `provider_tool_definition_invalid`, and the other
provider categories.
- `waiting_for_person`: `execution_reconciliation_required`, every code
in `EXECUTION_RECONCILIATION_CAUSES`, `issue_waiting_for_response`, and
`issue_continuation_waiting_on_review`.
- `task_changed`: the task was reassigned, paused, closed, blocked, or
stopped by a person (`operator_interrupted`, `cancelled`, `interrupted`,
`issue_*` lifecycle codes, `agent_paused`, `queued_comment_discarded`).
- `platform_error`: process, server, workspace, sandbox, runner, and
storage codes (`process_lost`, `server_shutdown_interrupted`,
`setup_failed`, `workspace_*`, `environment_provider_unavailable`,
`controller_lease_lost`, and others).
- `agent_error`: `adapter_failed` without a provider failure,
`invalid_output`, `invalid_response`, `tool_error`, `acpx_turn_failed`,
`test_run_failed`, `prompt_injection_blocked`,
`tool_execution_outcome_unknown`, `timeout`.
  - `unknown`: any other code, or no code.
- On Cloud direct delivery, every new emit site names the responsible
person with `withTelemetryActor()` and `resolveTelemetryPerson()`, as
`agent.task_run` does: the task creator, else the task's responsible
user, else the run owner. `task.created` uses the creating user, else
the agent's on-behalf user. `model.connected` uses the user who owns the
connection. A live request still wins. The self-hosted collector
envelope does not change.
- `failure_cause` builds on the run failure code sets in
`continuation-cause.ts`. A test fails when a code in those sets has no
telemetry code. The provider failure category decides only for
`adapter_failed`, `provider_failed`, or no code.
- Work product providers outside `paperclip`, `github`, `vercel`, and
`s3` are sent as `custom`.
- The dispatch workspace check and execution recovery write `blocked`
directly. They call the same after-commit helper, with the task's real
blockers and unblock owner. The blocker read runs in a savepoint in the
issue dependency layer, so a failed read never aborts the block write.
- Update the telemetry README with the emit rules, the after-commit
rule, and the `failure_cause` source.
- Refresh `tests/runner-e2e/source-sdk-public-inputs.json`, because its
check reported a change.

## Privacy Review

Privacy review requested. Every new dimension is a fixed enum, a
boolean, or a count. No dimension carries a title, a body, a plan step,
a connection or account name, an email, a URL, a repository name, a
prompt, an error message, or an endpoint address. `failure_cause` is a
code that the server picks. The run's error text is never sent. The
tests check that a provider message and a connection name do not reach
the event.

## Verification

- `pnpm vitest run packages/shared/src/telemetry/`: 7 files pass,
including the new `product-events.test.ts` (helper payloads, omitted
optional values, collector envelope with only registered dimensions,
retention class).
- `packages/db/src/after-transaction-commit.test.ts`: 4 pass (after
commit, rollback drop, savepoint, outside a transaction).
- `server/src/__tests__/product-telemetry.test.ts`: 14 pass. They check
that each event fires once with the right kind and company scope, that a
rollback sends nothing, that a repeated status sends nothing, that a
later plan revision sends nothing, and that a reconnect sends nothing.
- `server/src/__tests__/agent-task-run-telemetry.test.ts`: 35 pass,
including the `failure_cause` mapping table and the emit path.
- `server/src/__tests__/issue-thread-interactions-service.test.ts -t
Plan`: `plan.approved` fires for a plan confirmation and not for an
unrelated confirmation.
- `server/src/__tests__/posthog-direct-telemetry.test.ts`: the Cloud
direct path sends `company_id`, `user_id`, and `attributed_via` for
background lifecycle events, an event with no person stays on the
workspace, and `failure_cause` passes through. A self-hosted test checks
that a person scope leaves the collector events unchanged.
- Existing telemetry tests (connector, interaction, run finalizer,
heartbeat, AI connection): 299 pass.
- `pnpm --filter @paperclipai/shared typecheck`, `pnpm --filter
@paperclipai/db typecheck`, and `pnpm --filter @paperclipai/server
typecheck`: pass.
- `pnpm verify` returned exit 2 (global CI input changed). Required CI
supplies the broad coverage.

## Risks

- Merge order: merge and deploy paperclipai/telemetry-backend#150 first.
If this change ships first, the collector quarantines the new events.
The product behavior does not change.
- `afterTransactionCommit` uses the existing open-transaction marker in
the database client. A callback that a savepoint registers runs when the
outer transaction commits, even if that savepoint rolled back.
- `task.blocked` adds one small indexed read inside the update
transaction, only when a task enters `blocked`.
- `failure_cause` adds one small read for a failed run when the caller
did not pass the error code. It runs off the run's critical path, as
before.
- Low risk otherwise. No schema migration. No change to existing event
dimensions.

> 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

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code,
with tool use (shell, Git, tests).

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1119.0-canary.830300
2026-11-18 19:32:27 -06:00
7a0ac92fdf fix(runner): tell ACPX agents which field a refused semantic call failed (#22037)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents call Paperclip semantic tools (for example
`request_human_input`) through the runner, and the ACPX runner sends
each refusal back to the agent
> - Today the ACPX runner replaces every refusal with the fixed text
"Paperclip semantic operation failed"
> - The real reason (for example `summary: too big, max 1000`) is only
in the run events, so the agent cannot see it
> - Agents then retry the same bad input. One agent retried a questions
card 5 times with the same too-long prompt
> - This pull request adds the stable error code and, for a validation
refusal, each failing field path with its rule and limit to the message
> - The value the agent sent, free-text messages and server errors (5xx)
stay hidden, as before
> - The benefit is that agents can fix a refused call on the next try
instead of retrying blind

## Linked Issues or Issue Description

Refs #20134 (fixes one case of this problem: the advertised
`request_human_input` bounds)

**What happened?**
An agent called a semantic tool with input that failed server
validation. The tool result said only "Paperclip semantic operation
failed". The agent retried the same input 5 times, and each retry failed
the same way. The run events showed the real cause: `summary: too big,
max 1000`.

**What did you expect to happen?**
The tool result should say which field failed and which rule it broke,
so the agent can correct the input. It should not echo the input value
or internal diagnostics.

**Steps to reproduce**
1. Run an agent on an ACPX provider.
2. Call `request_human_input` with a `prompt` of 1,100 characters
(before #20134), or any semantic tool with input that fails zod
validation.
3. See the generic "Paperclip semantic operation failed" in the tool
result.

## What Changed

- New `acpx_tool_failure_feedback` module in `runner-core`. It reads a
failed tool result and builds a bounded message from:
- a stable error code (lowercase words joined by `_`, `.` or `-`, for
example `paperclip_runner_agent_not_found`);
- zod-style issues: field path, rule name, type and numeric limit, for
example `payload.prompt: too_big, string max 1000`.
- It reads the result as an object, an issue list, or a `{success:false,
contentItems:[{inputText}]}` envelope whose text is JSON or starts with
`code:`.
- It never copies `message`, `input`, free text or the input value. Path
keys and rule names that do not look like names become `*` or `invalid`.
It shows at most 5 issues and 8 path segments.
- Any result with a status of 500 or more, or with no recognizable code
or issue, keeps the generic message.
- `AcpxProviderSession` uses this message for non-terminal semantic
failures. Reserved terminal tools keep their current feedback.
- Fake ACPX sidecar mode `resolutions-error-detail` and an integration
test that checks the message crosses the sidecar boundary without the
value.

## Verification

- `cargo test -p runner-core --lib acpx_tool_failure_feedback` (7 unit
tests: issue lists, envelopes, codes, server errors, free text, masking,
bounds).
- `cargo test -p runner-core --test acpx_provider_resolutions` (new
`tells_the_agent_which_field_failed_validation_without_its_value`, and
the existing redaction test still gets the generic message).
- `cargo fmt --check`.

## Risks

- Low to medium. The main risk is data in error text. The module copies
only values that match strict name and number patterns, and never a
`message` or `input` field. Tests check that sample values do not appear
in the output.
- Agents see a longer error message for validation refusals. The message
still starts with "Paperclip semantic operation failed", so text matches
on that prefix keep working.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in an agent harness.

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: lucktastic <13757243+lucktastic@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1119.0-canary.830200
2026-11-18 16:49:11 -08:00
DottaandClaude Opus 5.5 92dbf39e6f feat(analytics): attribute agent work and onboarding steps to a person on Cloud (#22260)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Cloud sends product events straight to PostHog: server
events from `server/src/services/posthog-direct/` and browser events
from `ui/src/lib/analytics/`
> - A person-level funnel goes from sign-up to the first finished task
> - Agent-driven events (`agent.task_run`, `agent.task_completed`,
`agent.first_heartbeat`) used `workspace:<stackId>` as the distinct id,
so the funnel broke at those steps
> - The in-workspace onboarding wizard sent no step events, so we could
not see where people stop before their first agent
> - This pull request attributes agent work to the responsible person on
the Cloud direct path, and adds consent-gated onboarding step events in
the browser
> - The benefit is one PostHog person per customer across sign-up,
onboarding, agent runs, and task completion. Self-hosted output does not
change.

## Linked Issues or Issue Description

**Subsystem affected**
Cloud product analytics: Cloud direct PostHog delivery (server) and
browser product analytics (UI onboarding wizard).

**Problem or motivation**
A PostHog funnel from sign-up to the first finished task cannot follow
one person. Agent-driven events run in the background, with no signed-in
request, so they use the workspace id as the distinct id. The onboarding
wizard also sends no events, so we cannot see which step people leave.

**Proposed solution**
Give background emit sites a narrow scope that names the person
responsible for the work. Use the task creator first, then the task's
responsible user, then the run owner. Keep the signed-in request user
first. Add `attributed_via` to every Cloud direct event. Add four
browser events to the onboarding wizard. Send them through the existing
analytics module, so the consent rules stay the same.

**Alternatives considered**
A lookup in the transport at send time. We did not use it: it adds
database reads to the telemetry path and loses the emit site's context.
A new contract event for onboarding steps. We did not use it: the server
does not see the wizard steps, and the UI must never send
`PAPERCLIP_EVENTS` names.

**Additional context**
Self-hosted installs keep the collector path. The collector envelope
stays byte-identical (a test checks it).

## What Changed

- `server/src/telemetry-company-scope.ts`: add `withTelemetryActor({
companyId, person }, fn)`, `scopedTelemetryPerson()`, and
`resolveTelemetryPerson()`. The resolver picks the task creator, then
the task's responsible user, then the run owner. It ignores
`local-board`. `withTelemetryCompany` now calls `withTelemetryActor`.
- `server/src/services/posthog-direct/request-context.ts`: a signed-in
request user wins (`attributed_via: request`). Without one, the scoped
person is used.
- `server/src/services/posthog-direct/event-shape.ts`: every Cloud
direct event (including `cloud.workspace_started`) has `attributed_via`
(`request`, `task_creator`, `task_assigner`, `run_owner`, or `none`). An
event with a person keeps today's person-event shape (no
`$process_person_profile: false`).
- `server/src/services/agent-task-run-telemetry.ts`: `agent.task_run`
reads the task creator and responsible user in the existing agent query
(one left join, no new query), and the run's `responsibleUserId`.
- `server/src/routes/issues.ts`: `agent.task_completed` uses the issue
row that the route already has, and the agent actor's `onBehalfOfUserId`
as the run owner.
- `server/src/services/heartbeat/agent-status.ts`:
`agent.first_heartbeat` uses the agent's `createdByUserId` (already
loaded) as the run owner.
- `ui/src/lib/analytics/product-analytics.ts`: add
`captureProductAnalyticsEvent()`. It captures only with a browser
analytics config and granted consent. Events from before posthog-js
loads wait in a queue (at most 50) and keep their time. Withdrawn
consent or a change of signed-in person drops the queue.
- `ui/src/lib/analytics/onboarding-analytics.ts` and
`ui/src/components/OnboardingWizard.tsx`: capture `onboarding_opened`,
`onboarding_step_viewed`, `onboarding_step_completed` (with `step` and,
for `connect_model` and `launch`, `outcome`), and
`onboarding_dismissed`. `step` is `create_agent`, `connect_model`,
`review`, or `launch`. No event has free text.
- Docs: `packages/shared/src/telemetry/README.md` (Cloud Direct
Delivery) and `doc/cloud-browser-analytics.md` (new "Onboarding events"
section).

## Verification

- `server/src/__tests__/posthog-direct-telemetry.test.ts`: attribution
matrix (creator, assigner, run owner, none stays on
`workspace:<stackId>` with `$process_person_profile: false`), the
request user wins over the scope, and the self-hosted collector envelope
is byte-identical with a person scope.
- `server/src/__tests__/agent-task-run-telemetry.test.ts` (embedded
Postgres): `agent.task_run` scope for creator, assigner, run owner, and
nobody; another company's task is never read.
- `server/src/__tests__/issue-telemetry-routes.test.ts`:
`agent.task_completed` scope for creator and assigner.
- `server/src/__tests__/heartbeat-process-recovery.test.ts`:
`agent.first_heartbeat` scope is the agent owner.
- `ui/src/components/OnboardingWizard.test.tsx`: a launch for the old
company that settles after a switch to another company does not end the
new analytics session.
- `ui/src/lib/analytics/onboarding-analytics.test.tsx`: each transition
fires once, held events drop on a person change, a stale opening step is
not a view, dismissal fires once, nothing is captured when analytics is
off or consent is `denied` or `ask`, and queued events keep their time.
- `ui/src/lib/analytics/product-analytics-events.test.ts` still passes
(the UI never captures a `PAPERCLIP_EVENTS` name).
- Local Cloud-mode run: an isolated instance (own Postgres, trusted
Cloud tenant headers, `PAPERCLIP_POSTHOG_HOST` set to a local capture
server, never real PostHog). A stub stood in for posthog-js and sent
through the `/_ph` proxy.
- A user created a task and assigned it to the agent. `agent.task_run`
arrived with `distinct_id: paperclip-id:local-user-1`, `attributed_via:
task_creator`, the raw `task_id`, and no `$process_person_profile`. (The
run itself failed locally because the Cloud runner is not available. The
event still shows the attribution.)
- `agent.first_heartbeat` arrived with the same person and
`attributed_via: run_owner`. `server.started` kept
`workspace:stack-local` with `attributed_via: none`.
- Headless Chromium walked the wizard: `onboarding_opened`
(create_agent), `onboarding_step_viewed` (create_agent),
`onboarding_step_completed` (create_agent), `onboarding_step_viewed`
(connect_model), `onboarding_step_completed` (connect_model, `api_key`),
`onboarding_step_viewed` (review), `onboarding_step_completed` (review),
`onboarding_step_completed` (launch, `succeeded`). Each fired once, with
the signed-in user as the distinct id. Events from before posthog-js
loaded arrived with their original time.
- A second walk left the onboarding page on the connect step and sent
one `onboarding_dismissed` (connect_model).

## Risks

- Low risk for self-hosted: the collector path never reads the new
scope, and a test checks the envelope bytes.
- Cloud: agent events move from the workspace person to a real person.
Insights that count `workspace:` distinct ids for these events will
change. `attributed_via` lets a query filter or split them.
- `task_assigner` uses the task's responsible user. Paperclip does not
store who assigned a task, so this is the person who owns or delegated
the task.
- Privacy: the new data is Cloud-only and uses ids that Cloud events
already carry. No new free text, email, or name goes on an event.
**Privacy review requested** for the Cloud attribution change (per
`rules/data-paths.mdc`). The generated contract does not change:
`attributed_via` is a Cloud-only property, like `stack_id` and
`user_id`.

> 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

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, headless browser).

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 18:44:45 -06:00
e2cee049f9 fix: show instruction saves in history, credit the real writer, and speed up the agent tool-rule list (#19515)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Operators and agents change agent instructions (AGENTS.md), and they
must see who changed them and when
> - Agent files replaced instruction revisions. Saves no longer write
revision rows, so instruction history is empty
> - The current revision is stamped with the reader and the date
1970-01-01, so it gives false audit data
> - Separately, an agent that lists tool rules gets a timeout when many
rules name the same resources
> - This pull request reads history from the save records that Paperclip
already writes, credits the real writer, and checks each tool-rule
resource one time
> - The benefit is a correct audit trail for instruction changes and a
tool-rule list that agents can read

## Linked Issues or Issue Description

No public issue exists. I searched open and closed issues and PRs for
these problems and found none.

**What happened?**
1. `get_agent_instruction_history` (and the history API) returns 0
revisions for an agent whose AGENTS.md was saved many times. The
activity log shows each save as `agent.files_updated` with the path,
content hash, actor and run.
2. `read_agent_instructions` returns a current revision with `createdAt`
1970-01-01. Its actor is the agent that reads it, and its `sourceRunId`
is the run that reads it.
3. `GET /api/companies/{companyId}/tools/policies` from an agent fails
with a transport timeout most of the time when the company has many tool
rules. A board user gets the list without a problem.

**Expected behavior**
1. History lists each save, newest first, with its writer, run, source
and time.
2. The current revision names the agent or user that wrote those bytes,
and the time of that save. If no save is recorded, it names no writer.
3. The agent gets the tool-rule list in normal time, with the same rules
hidden as before.

**Steps to reproduce**
1. Save an agent's instruction entry file (board editor,
`update_agent_instructions`, or a run that edits the file). Read the
history. It is empty.
2. As a different agent, call `read_agent_instructions` on that agent.
The revision shows the reader and 1970-01-01.
3. Create about 40 tool rules that name the same connection and agent.
As an agent, list `/tools/policies`. Each rule does a new set of access
checks for each resource, one after another.

**Paperclip version or commit**
`master` at `819420a60a`.

**Deployment mode**
Hosted. The new tests reproduce all 3 problems on `master`.

## What Changed

- `agent-instruction-revisions.ts`: history merges the legacy revision
rows with the `agent.files_updated` save records for the entry file. The
order is `(created_at, id)` descending, and cursors keep PostgreSQL
timestamp precision.
- `agent-instruction-revisions.ts`: the current revision takes its
writer, run, source and time from the latest save of the same content
hash. A reader is never the writer. Bytes with no save record have no
writer.
- `agent-instruction-revisions.ts`: an identical re-save over bytes with
no record is marked `source: "adopted"`. It repairs the runtime journal
but is not listed as a save.
- `agent-instruction-revisions.ts`: a history ID can be a legacy
revision, a save record, or the current content token. A save record
keeps only metadata. If its bytes are no longer current, a read returns
404 with `INSTRUCTION_REVISION_CONTENT_NOT_RETAINED`.
- `agent-file-store.ts`: saves record `byteLength`. A run collection
that changes the entry file records its path, hash and size, so history
shows saves from runs.
- `connection-management-authz.ts`: `filterConnectionManagementPolicies`
keeps one read decision for each distinct resource in a request, and
loads each application or catalog entry one time. A rule is still hidden
when any resource that it names is hidden. Board callers do not use this
path.
- Tests: new tests for save history, paging, writer credit, adoption,
and the tool-rule list. Old assertions that expected empty history now
check the exact saves.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/agent-instruction-revisions.test.ts
src/__tests__/agent-instruction-working-copies.test.ts
src/__tests__/agent-directory-working-copies.test.ts
src/__tests__/built-in-agents.test.ts
src/services/native-runtime/agent-instruction-tools.integration.test.ts
src/__tests__/tool-policy-list-authz.integration.test.ts`
- With the fix: all pass (revisions: 28 passed, 1 skipped on Linux;
other 5 files: 230 passed).
  - With the new tests on `master` code: 13 tests fail, as expected.
- `src/__tests__/connection-management.integration.test.ts`: 90 passed.
- The new tool-rule test lists 40 rules that name 1 connection and
counts the connection reads. It needs fewer than 10.
- I could not run the full server typecheck in my sandbox because of a
memory limit. CI runs it.
- CI on head `a2f0b825`: all checks pass, including `ci / verify` and
`ci / e2e`.

## Risks

- History now shows entries whose ID is an activity row ID, not a
revision row ID. Clients that read or restore an older save get a clear
404 because Paperclip no longer keeps those bytes. The latest save and
legacy revisions still read and restore as before.
- Saves recorded before this change have no `byteLength`. For those,
history shows the current size when the hash matches, and 0 otherwise.
- Stock updates of built-in agents do not record a file path, so they do
not show in history.
- No migration. No change to the stored data model.

> 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

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with
tool use (shell, file edits, test runs). 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
- [ ] 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: lucktastic <13757243+lucktastic@users.noreply.github.com>
2026-11-18 16:41:53 -08:00
Devin FoleyandPaperclip 75ae377438 feat(ui): offer to cancel active subtasks (#22228)
Offer to cancel readable active subtasks when a task is canceled. Show a counted heading, status icons and titles, with choices to cancel only the parent or also its listed subtasks. Include waiting chat descendants and skip terminal or moved tasks observed before each write.

Verified with focused UI and database tests, final CI, Greptile 5/5 with no unresolved comments, and manual acceptance.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-11-18 16:41:06 -08:00
6b980871b5 fix(grok-local): copy SSH skill contents into the created directory (#22120)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The `grok_local` adapter can run a Grok agent on a remote SSH
workspace
> - Before the run, `prepareGrokRemoteProjectAssets` copies the selected
skills into `.claude/skills` on the target
> - It creates each skill directory and then calls `fs.cpSync` on that
same directory with `force: false` and `errorOnExist: true`
> - Node 24 rejects this with `ERR_FS_CP_EEXIST`, so every Grok run over
SSH fails with "Could not prepare Grok SSH runtime assets"
> - This pull request copies the contents of each skill into the new
empty directory
> - The benefit is that Grok SSH runs work again and the shared CI test
groups go green on master and on open PRs

## Linked Issues or Issue Description

Refs #22078

**What happened?**
Every Grok run on an SSH target fails before it starts. The error is
"Could not prepare Grok SSH runtime assets". The script on the target
fails with `SystemError [ERR_FS_CP_EEXIST]: Target already exists: cp
returned EEXIST (.../.claude/skills/selected already exists)`.

**Steps to reproduce**
1. Use Node 24.
2. Run `pnpm --filter @paperclipai/adapter-grok-local exec vitest run
src/server/remote-project-assets.test.ts`.
3. The "existing", "new" and "changed" cases fail.

**Expected behavior**
The skills are copied into `.claude/skills/<name>`, and the existing
project files stay safe.

**Impact**
CI fails on master and on unrelated open PRs:
- `ci / General tests (workspaces-b)`, in
`remote-project-assets.test.ts`
- the server group that runs `ssh-remote-workspace.integration.test.ts >
runs an assigned grok_local-cli task through heartbeat over SSH`

## What Changed

- `packages/adapters/grok-local/src/server/remote-project-assets.ts`:
after the script creates a skill directory, it now copies each child of
the source skill into that directory. Before, it copied the skill
directory onto itself. The copy keeps `force: false` and `errorOnExist:
true`, so it still does not overwrite files.

## Verification

- Red: on `origin/master` with Node v24.22.3,
`remote-project-assets.test.ts` fails 3 of 4 cases with
`ERR_FS_CP_EEXIST`. I saw this error in the script's stderr.
- Green: with this change, `vitest run src/server` in
`packages/adapters/grok-local` passes 137 tests in 9 files, and all 4
cases of `remote-project-assets.test.ts` pass.
- I could not run the SSH integration test locally. It needs a real SSH
server, so it is skipped here. CI runs it.

## Risks

Low risk. The change affects only the copy step for each new skill
directory. Cleanup and the safety checks for symlinks and paths do not
change. The script creates the target directory just before the copy, so
the directory is empty.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, test runs).

## 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
- [ ] 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

The existing `remote-project-assets.test.ts` cases already cover this
bug: they fail before the fix and pass after it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: lucktastic <13757243+lucktastic@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 16:30:51 -08:00
DottaandClaude Opus 5.5 c600d69242 Let plugin connectors declare their tool timeout (#22249)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Plugins can serve connector tools from their worker (`transport:
"plugin"`, added in #22004, #22019 and #22201).
> - The tool gateway runs these tools with a fixed 10 s default timeout.
> - Some plugin tools call backends that take 12–20 s. These calls fail
every time with "Tool execution timed out", even though the plugin's own
HTTP client waits much longer.
> - The plugin connector design said that the connector, not a fixed
gateway constant, sets the timeout.
> - This pull request lets a plugin method or a single static tool
declare `timeoutMs`, and gives plugin-served tools a 30 s default.
> - The benefit is that a plugin connector can serve slow tools like
other connectors can, within the same 60 s gateway ceiling.

## Linked Issues or Issue Description

Refs #22004, #22019, #22201. Refs #20746.

**Relationship to #20746.** This PR builds alongside #20746. It does not
supersede it. #20746 changes the default for legacy top-level plugin
tools (provider `paperclip_plugin`) to 60 s. This PR changes only
plugin-served connector tools (provider `paperclip_plugin_connection`,
`transport: "plugin"`). The two PRs touch different branches of the
gateway and can merge in either order. This PR does not pin the legacy
default in its tests, so #20746 does not break them.

**Current behavior**
A plugin connector tool always times out after 10 s, unless the caller
sends `timeoutMs`. Agents and runners do not send it. The worker RPC
also stops at 30 s.

**Proposed behavior**
A plugin can declare `timeoutMs` (1000–60000 ms) on a `transport:
"plugin"` method or on one static tool. The gateway uses that value. If
nothing is declared, the gateway waits 30 s.

**Reason and benefit**
Plugin tools whose backends take longer than 10 s can now work. Plugin
authors control the value in the manifest, and the gateway keeps its 60
s ceiling.

**Breaking changes**
None. Existing manifests stay valid. Only plugin-served tools get the
new 30 s default.

## What Changed

- `packages/shared`: `timeoutMs` is a new optional field on
`ConnectionMethodDef` and on `PluginConnectorToolDef`. The validator
accepts integers from 1000 to 60000 only. It rejects `timeoutMs` on
methods that do not use `transport: "plugin"`. New exported constants:
`PLUGIN_CONNECTOR_TOOL_TIMEOUT_MIN_MS`,
`PLUGIN_CONNECTOR_TOOL_TIMEOUT_MAX_MS`, and
`PLUGIN_CONNECTOR_TOOL_DEFAULT_TIMEOUT_MS` (30000).
- `server/src/services/plugin-connector-runtime.ts`:
`pluginConnectionToolTimeoutMs()` resolves the timeout in this order:
the tool's value, then the method's value, then 30 s. The worker
`executeTool` RPC now gets the gateway timeout plus 1 s. Thus the
gateway's `tool_timeout` error is what callers see, and the 30 s RPC
default no longer cuts off a longer declared timeout.
- `server/src/services/tool-gateway.ts`: `executePluginConnectionTool`
now applies the timeout itself, after it loads the connection. All three
plugin paths use it: session, assigned-tool and direct calls
(`executeTool`), test calls (`executeTestCall`), and approved action
execution. If a caller sends `timeoutMs`, that value wins, as before. It
is still clamped to 60 s. Approved actions keep their fixed 60 s budget.
- Other transports do not change. Remote MCP, local stdio, built-in and
legacy plugin tools keep their timeouts. (#20746 separately proposes a
60 s default for legacy plugin tools.)
- Docs: `doc/plugins/PLUGIN_SPEC.md` §11A and the plugin SDK README
describe the field, its range, and the default. The SDK manifest type
gets the field from `@paperclipai/shared`.

### Why 30 s

30 s is the same as the plugin worker manager's default RPC timeout. So,
before this change, the worker already allowed 30 s, and only the
gateway's 10 s limit stopped the call. With 30 s, the common 12–20 s
backend case works without a declaration. It is also well under the 60 s
ceiling. Tools that need more time can declare up to 60 s.

## Verification

- New `server/src/__tests__/plugin-connector-tool-timeout.test.ts` runs
the real gateway invocation path against an embedded Postgres and a fake
worker. Fake timers make the 12 s backend free in wall-clock time:
- With method `timeoutMs: 30000`, a 12 s tool succeeds through
`executeTool` and through `executeTestCall`. The worker RPC timeout is
31000.
- With tool `timeoutMs: 5000`, a 12 s tool fails at 5 s with `504
tool_timeout`.
- With no declaration, a 12 s tool succeeds (it failed at the old 10 s),
and a 45 s tool times out at 30 s.
- Manifest values above 60000, below 1000, or not integers are rejected.
A caller `timeoutMs: 120000` is clamped to 60 s.
- A legacy plugin tool (`paperclip_plugin`, a different provider path)
never reaches the connector runtime, and a caller deadline still
applies. This test does not pin the legacy default, because #20746
changes it.
- Remote MCP, local stdio and REST timeouts do not change in this PR.
Their existing timeout tests in `tool-gateway.test.ts` and
`google-workspace-rest-transport.test.ts` still apply.
- Red/green: with the source change reverted, 4 of these 5 tests fail.
The legacy-tool test passes both ways, as expected.
- `packages/shared/src/plugin-apps.test.ts`: validation cases for the
range, non-integer values, and non-plugin methods.
- Commands run:
- `pnpm --filter @paperclipai/shared typecheck && pnpm --filter
@paperclipai/server typecheck && pnpm --filter @paperclipai/plugin-sdk
typecheck`
- `cd server && npx vitest run
src/__tests__/plugin-connector-tool-timeout.test.ts
src/__tests__/plugin-connectors-plugin-transport.test.ts
src/__tests__/plugin-connector-agent-grant.test.ts` (20 passed)
- `cd packages/shared && npx vitest run src/plugin-apps.test.ts
src/app-definitions.test.ts` (76 passed)
  - `pnpm check:module-boundaries`
- Full suite not run locally. CI supplies it.

## Risks

- Low risk. Plugin-served tools now wait up to 30 s instead of 10 s by
default. An agent turn can wait longer for a slow or stuck plugin tool,
but never longer than the existing 60 s ceiling.
- The connection row lookup now runs before the timeout timer starts.
This is one indexed query.
- Dynamic tool lists (`kind: "dynamic"`) use the method's `timeoutMs`.
Per-tool values apply to static tools only.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), through Claude Code with tool use
(shell, file edits, test runs).

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 18:24:03 -06:00
Devin FoleyandPaperclip d4b7ae5532 fix(tasks): require merged PR deliverables before native completion (#22244)
Keep native tasks with declared pull request deliverables active until
GitHub verifies every deliverable is merged. Preserve delivery guidance
in follow-up contracts and recheck the current outputs under task locks.

Use bounded incomplete-work feedback during reassessment, including for
saved non-Done reports. Serialize work-product restoration and identity
changes with completion. Preserve configured reviews and conversations.

Add regression coverage and repair the CI fixtures exposed during
qualification. All CI checks pass on afee630120. Greptile is 5/5 with no
unresolved review threads.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
canary/v2026.1119.0-canary.829600
2026-11-18 16:20:17 -08:00
673742bfc6 fix(ui): keep artifact previews in agent chat (#22252)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agent Chat lets people discuss work and review the plans and
documents it produces.
> - A document link in Chat promises to open the sidebar. It currently
moves the reader to Tasks.
> - Readers need to see the document and the conversation together, even
when the window is narrow.
> - This pull request opens the document in Chat, frees space for
reading, and gives readers a link to the source task.
> - Readers can review the saved revision in context and open the task
when they need its details.

## Linked Issues or Issue Description

Refs #11226 for the document sidebar that this change builds on.

**What happened?**

Opening a saved plan from Agent Chat changed the route to Tasks. The
document could show the same title twice. At narrow desktop widths, the
chat list left too little space for the conversation beside the
document. A task opened by UUID could still show a Chat header.

**Expected behavior**

The sidebar shows the saved revision beside the current conversation. It
shows a matching title once. The chat list collapses when space is
tight. The source link opens the standard task header with status, name,
and ID.

**Steps to reproduce**

1. Open an Agent Chat with a saved plan and select its sidebar link.
2. Use a narrow desktop window and inspect the conversation and plan.
3. Open the task that owns the plan and inspect the breadcrumb.

**Paperclip version or commit**

Reproduced on source commit `8285a81280`.

**Deployment mode**

Local trusted development instance with synthetic data.

## What Changed

- Open sidebar document links on the current Chat route. Keep the
requested revision and document owner, including links inside another
task’s preview. Provide an **Open source task** link.
- Show one title when the document title matches the opening Markdown
heading.
- Collapse the desktop chat list when an artifact tab would leave less
than 420 px for the conversation. Keep **Browse chats** in the header
with access to saved chat history. Restore the list when there is room.
- Use the task breadcrumb on task URLs, with the short UUID for a
conversation-backed task without a number.

## Verification

- Ran 618 focused Vitest tests across 18 UI files on the published
revision `2ff6c9e931`. All passed.
- Ran `pnpm --filter @paperclipai/ui typecheck`. It passed.
- Checked the synthetic demo in Chromium. Opened the plan in Chat,
checked the title, resized the window, and followed **Open source task**
to check its breadcrumb. Also verified a link inside a preview owned by
another task.
- Reproduced the chat navigation failure from the CI trace. The same
Playwright test passed locally after limiting collapse to artifact tabs.
- GitHub CI passed on `2ff6c9e931`, including build, typecheck, and all
browser shards. The remaining jobs passed on a retry after runner
shutdowns and a server handover test failure. The handover suite also
passed locally (19 tests). [GitHub
CI](https://github.com/paperclipai/paperclip/actions/runs/44423540581/attempts/2)
- `pnpm verify` selected broader CI coverage because `doc/PRODUCT.md`
changed. The full local suite was not run.

## Risks

The chat list changes visibility when an artifact tab is active and the
available width crosses the threshold. The list stays mounted to keep
its search text. Document tabs use the existing read API and check the
owning company. This change adds no database migration or API contract
change.

## Model Used

OpenAI Codex (GPT-6), with repository tools, shell execution, and
Chromium.

## 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 linked existing issues or described the issue in-PR
following the relevant issue template
- [x] I have used public GitHub references for linked work
- [x] My branch name describes the change and contains no internal
Paperclip ticket ID
- [x] I have run focused 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: Scott Tong <1504818+scotttong@users.noreply.github.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-18 16:19:13 -08:00
52cf30f131 test(release-smoke): follow onboarding into the standing chat (#22259)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The release workflow runs a Docker onboarding smoke on the real npm
artifact before it publishes a nightly or beta
> - #22077 changed onboarding. "Get started" now opens the lead's
standing chat. It does not create a first task or project
> - That PR updated the e2e tests, but it did not update the release
smoke
> - The smoke still expects an `/issues/` landing, so every nightly
smoke fails, and no nightly can publish
> - This pull request changes the smoke to assert the new chat-first
contract
> - The benefit is that the nightly lane can publish again, and the
smoke still guards the first-run experience

## Linked Issues or Issue Description

Refs #22077

**What happened?**
The release smoke `docker-auth-onboarding.spec.ts` fails at
`expect(page).toHaveURL(/\/issues\//)`. The page is on
`/<prefix>/chats/<agent id>`. The failure occurs on the first attempt
and on the retry. The scheduled nightly on 2026-11-18 and a dispatched
nightly for `2026.1118.0-canary.828200` both failed at this step.

**Steps to reproduce**
1. Run the release workflow with `channel=nightly` on a canary that
contains #22077.
2. Look at the `smoke_nightly / smoke` job.

**Expected behavior**
The smoke follows onboarding into the chat and passes when the artifact
works.

## What Changed

- Expect the launch to land on `/chats/<lead agent id>`, not on
`/issues/`.
- Assert that the task list and the project list are empty after launch.
- Assert that exactly one chat exists, with `originKind:
"onboarding_chat"`, no project, and the lead as `conversationAgentId`.
- Assert that the chat composer renders.
- Replace the old "no run" check. Now the smoke polls until the live
welcome run is queued for the lead. The provider mock serves no
completions, so the smoke does not check the welcome text.
- Remove the `FIRST_TASK_TITLE` constant, because onboarding no longer
seeds a task.

## Verification

- `tsc --noEmit --strict` on the spec passes.
- I checked the asserted fields against
`server/src/services/onboarding-chat.ts`, `GET
/companies/:companyId/chats` and
`tests/e2e/conference-room-typing-intro.spec.ts`.
- Full check: the `Release Smoke` workflow (or a nightly dispatch after
merge) must pass the `smoke` job.

## Risks

- Low risk. The change is test-only.
- The welcome-run assertion depends on the UI requesting the welcome in
a visible headless tab. If that is not true in CI, the poll times out
after 30 seconds. Then remove or relax that one assertion.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use (shell, GitHub
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
- [ ] 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 16:12:17 -08:00
DottaandClaude Opus 5.5 11d777b80f feat(server): fit PostHog proxy limits to busy Cloud stacks and make them configurable (#22243)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - On Paperclip Cloud, the board UI sends browser analytics to PostHog
through a same-origin proxy at `/_ph`
> - The proxy limits requests in flight: 16 per client address and 256
in total
> - Each open tab runs posthog-js, and one tab can have a few requests
in flight at once
> - On Railway without `TRUST_PROXY`, `req.ip` is the private edge hop,
so all visitors share one 16-request limit
> - This pull request raises the limits, makes them configurable, and
stops the per-client limit when `req.ip` is a shared private hop
> - The benefit is that busy stacks with many users and many tabs do not
lose analytics to 429 answers, and ops can see when a limit is hit

## Linked Issues or Issue Description

**Subsystem affected**
Server: the PostHog reverse proxy for Cloud browser analytics
(`server/src/routes/posthog-proxy.ts`).

**Problem or motivation**
The proxy limits are too low for busy Cloud stacks. One user with many
tabs can use 16 requests in flight. Behind the Railway edge without
`TRUST_PROXY`, `req.ip` is a private `100.64.x.x` hop, so all visitors
share one 16-request limit. The proxy then answers 429 and posthog-js
drops or delays events and replay uploads. Ops cannot change the limits
and cannot see when the proxy refuses requests.

**Proposed solution**
Raise the defaults to 128 per public client address and 1024 in total.
Read both limits from two environment variables with a strict parse and
a ceiling. When `req.ip` is not a public address, apply only the total
limit. Give each request a 60 second deadline. Log a warning at most
once a minute when the proxy refuses requests at a limit.

**Alternatives considered**
Find the visitor for the per-client limit from `X-Forwarded-For`. A
client can write that header, and an earlier security review asked the
proxy to keep `req.ip` as the key, so this change does not do that.
Scale the per-client limit for a shared hop. All visitors share the hop,
so a scaled limit is only a second total limit. The proxy applies the
total limit alone instead.

**Additional context**
Fleet operators can set the variables with an `env_config` campaign.
`doc/cloud-browser-analytics.md` tells how. Refs #22012 (the proxy) and
#22052 (visitor address behind a private hop).

## What Changed

- Raised `DEFAULT_POSTHOG_PROXY_LIMITS` to 128 requests in flight per
client address and 1024 in total. The 64 MiB body limit did not change.
- Added `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT` and
`PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT_PER_CLIENT`.
`resolvePostHogProxyLimits` reads them where `resolvePostHogProxyMount`
builds the proxy. A value must be a whole number from 1 to 65536. An
invalid value logs a warning and uses the default. The server does not
stop.
- Added `posthogProxyClientKey`. It returns `req.ip` only when it is a
public address. For a private, carrier-grade NAT, loopback, link-local
or other reserved address, or no address, the proxy applies only the
total limit. The key never comes from a client header.
- Added `createPostHogProxyLimitReporter`. When the proxy answers 429,
it logs `PostHog proxy refused requests at its in-flight limit` at most
once a minute. The fields are the refusal counts per limit since the
last warning, the requests in flight, the limits and the time since the
last warning. The warning has no addresses. It uses no timer: it checks
the time when a refusal occurs.
- Added a request deadline of 60 seconds from the time the proxy accepts
a request. At the deadline, the proxy stops the request to PostHog and
closes the browser response, also when PostHog already finished and the
browser does not read the response. The slot is then free again. Before,
the 30 second upstream timeout was an idle timeout, so a slow body that
sent a byte at a time could hold a slot until the server request timeout
(300 seconds).
- The mount object now also returns the limits in use.
- Updated `doc/cloud-browser-analytics.md`: the limits, why these
defaults, the variables, the shared-hop behavior, the warning fields and
how to tune a fleet with an `env_config` campaign.

Why these defaults:

- 128 per address covers about 10 people behind one office network, each
with 4 tabs and 3 requests in flight per tab, with space left over.
- 1024 in total keeps memory bounded. The proxy streams bodies, so a
request holds two sockets and the stream buffers between them, not the
full body. In a local test on this branch, 1024 held requests added
about 96 MiB of resident memory with 4 KiB bodies and about 173 MiB with
256 KiB bodies (256 held requests with 4 KiB bodies: about 40 MiB).
These numbers include the test client and the test upstream in the same
process, so the proxy share is smaller. Operators can lower the limit
for small stacks.

## Verification

- `cd server && npx vitest run
src/__tests__/cloud-posthog-browser.test.ts`: 87 tests pass (5 runs in a
row).
- New tests:
- Defaults, values from the environment, an empty value, and invalid
values (`0`, `-5`, `1.5`, `1e3`, `12abc`, `abc`, `0x10`, `+8`, `65537`,
`1024000`, a value larger than a safe integer). `65536` is accepted.
Each invalid value keeps the default and warns once per variable.
  - The mount passes the configured limits to the proxy.
- Per-client limit for a public address (with `trust proxy` set): a
second request from the same address gets 429, a request from another
address gets 200.
- Shared private hop (no trusted proxy, peer is loopback): the
per-client limit does not apply, and the total limit still answers 429.
- A forged `X-Forwarded-For` does not select the bucket when no proxy is
trusted: three held requests with the same forged public address and a
per-client limit of 1 all get 200.
- Request deadline: an upstream that does not answer gives 502 at the
deadline and frees the slot, a body that trickles in is cut off at the
deadline, and a 16 MiB response that the browser does not read is closed
at the deadline.
- The tests wait until the held upstream receives each request, not for
a fixed time.
- Total limit across public addresses, and the reported reason (`total`
or `per_client`) for each 429.
- The warning rate limit: one warning for the first refusal, none in the
next 60 seconds, then one warning with the counts of the refusals in
between, and no addresses in any warning.
- Red/green: with the shared-hop rule removed (`posthogProxyClientKey`
returns `req.ip`), 9 of the new tests fail. With the deadline removed,
the 2 deadline tests fail. With both, all pass.
- `cd server && npx tsc --noEmit -p tsconfig.json`: passes.
- `pnpm verify`: exit 2, because `doc/cloud-browser-analytics.md` is a
global CI input. Required CI supplies the broad coverage.
- Memory numbers come from a local script that held 1024 requests
through the proxy against a local upstream (Node 26, macOS).

## Risks

- Higher limits let more requests use memory and sockets at once. The
worst case is bounded by the total limit, and operators can lower it
with `PAPERCLIP_POSTHOG_PROXY_MAX_IN_FLIGHT`.
- Behind a shared private hop, one client can use all of the total
limit, and other visitors then get 429. The request deadline frees each
slot after at most 60 seconds, but a client that sends again can keep
the limit full. Before this change, the same visitors shared a limit of
16, which one client could also fill. A separate limit for the hop would
not help the visitors behind it, because one client that fills it blocks
all of them. Setting `TRUST_PROXY` brings back the per-client limit.
- A PostHog request that takes longer than 60 seconds now fails with
502. posthog-js bodies are small and PostHog answers in well under a
second, so this does not affect normal traffic.
- If an operator sets `TRUST_PROXY` to trust every hop, `req.ip` comes
from the client's `X-Forwarded-For`. This was already true before this
change. The total limit still applies.
- The proxy is mounted only on Cloud with browser analytics on.
Self-hosted installs do not change.

> 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

- Claude Opus 5.5 (claude-opus-5-5), Anthropic, used through Claude Code
with tool use (shell, file edits, test runs).

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 18:05:52 -06:00
4434714824 Fix sidebar Recents task order and archive visibility (#22251)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The sidebar gives people quick access to tasks, chats, and projects
they recently opened.
> - Expanding a parent or project in Recents can show tasks the person
never opened.
> - Archiving a task from the inbox leaves it in Recents.
> - This change gives each recent task its own row and removes tasks
archived for the current viewer.
> - People can reopen an individual task and keep saved shortcuts above
More.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Recents in the Standard and Classic sidebars.

**Subsystem affected**

Board navigation and task summaries.

**Current behavior**

Opening a parent or project can show other tasks beneath it. A recent
subtask moves its parent group when reopened. Archiving a task leaves
its recent link visible.

**Proposed behavior**

Show each visited task in its own row, in recent activity order. Keep
canceled and completed tasks eligible. Remove tasks archived for the
current viewer from Recents. Preserve saved pins.

**Reason and benefit**

People can find the task they opened by its own position in the list.
Archiving removes its recent link without removing a saved shortcut.

**Breaking changes**

The Recents rows no longer expand into task lists. Project links still
open the project. The navigation summary adds an optional personal
archive flag.

Related work: #22219, #22024, #21904, and #20450.

## What Changed

- Render task, agent chat, and project rows directly in Standard
Recents. Keep the existing controls to pin each kind of row.
- Render standalone task rows with the existing Classic action menus.
Remove sidebar child loading and refresh code.
- Derive the viewer’s archive state using the existing inbox rule.
Filter archived tasks out of Recents while retaining authorized pinned
shortcuts.
- Cover independent parent and child order, canceled and archived tasks,
pin retention, and the Classic Archive action.

## Verification

- Reproduced the empty Recents row after cancellation before the fix.
- On the rebased branch, 424 focused UI and live-update tests and the UI
typecheck passed on macOS.
- Ran 77 issue-summary and OpenAPI integration tests with embedded
PostgreSQL on macOS. The Runner source SDK registry check passed on the
pushed revision.
- The updated sidebar test renders 402 recent rows. A deliberate
repeated task lookup made the input-read guard fail. The restored
implementation passed.
- The paused-assignee browser test checks the task detail heading in
each interface. Both variants reproduced the CI locator failure locally
and passed with the scoped locator.
- All 17 focused Storybook browser checks passed in Chromium on macOS.
- Run `pnpm verify` for local selection. The product documentation
change requests broader GitHub CI coverage.
- Open a parent task and a child task in either sidebar. Reopen the
child and check that its row moves ahead of the parent. Cancel the child
and check that it stays visible. Archive it and check that its recent
row disappears.

- On commit `8051038099`, [GitHub
CI](https://github.com/paperclipai/paperclip/actions/runs/44421716811)
passed, including the required verification and end-to-end checks.
-
[Greptile](https://github.com/paperclipai/paperclip/pull/22251#issuecomment-6994494812)
rated the same commit 5/5. Its review thread is resolved.

## Risks

- Recents uses the same viewer-specific archive rule as the inbox.
Archiving prunes the local recent entry. A restored task can enter
Recents again when opened.
- Task summaries still return authorized tasks for saved pins. Child and
unread counts remain in the existing API response for older clients.
- The change requires no database migration.

## Model Used

- OpenAI GPT-6 via Codex with shell, GitHub CLI, Vitest, and Chromium.

## 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: Scott Tong <1504818+scotttong@users.noreply.github.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-18 16:04:42 -08:00
DottaandPaperclip 3f263e4faf feat(ui): align routine controls and remember list views (#22182)
## Thinking Path

> - Paperclip helps people manage AI agents and their work.
> - Routines define recurring work and create tasks.
> - People need the same controls to find and inspect routines as they
use for tasks.
> - The routine list had different search controls and no detailed
filters or column choices.
> - This pull request aligns the controls and remembers each person's
view.
> - People can share a filtered link and see the responsible person
beside the agent.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The Routines list controls and metadata in the current and classic
interfaces.

**Subsystem affected**

ui/ — the React board.

**Current behavior**

Routines use different search controls from Tasks. The list has limited
view settings and no filters for project, agent, enabled state,
responsible person, or source. Routine metadata is fixed.

**Proposed behavior**

Show New routine on the left. Show Search, Sort, Filter, Group, Columns,
and View all tasks on the right, in that order. Use the shared Tasks
search and filter controls. Show the responsible person next to the
agent. Let people choose metadata columns. Save filters, search, sort,
and grouping in the URL. Remember view settings per person and company
in local storage. Use a play icon for manual runs.

**Reason and benefit**

People can scan routine ownership, find a subset, share its link, and
return to their preferred columns and view.

**Breaking changes**

The list uses metadata columns with horizontal scrolling on narrow
screens. Existing company-level sort and group preferences are read as a
fallback. No API or database change is required.

Related work: Refs #22009, Refs #18606, Refs #18317. The open PR search
found no duplicate of this list-control change. ROADMAP.md lists
Routines as shipped and has no overlapping control work.

## What Changed

- Align both Routines toolbars with the requested order and shared
search and button styles.
- Extract the existing Tasks filter group and checkbox row for reuse by
Routines.
- Add project, agent, enabled, responsible person, and source filters.
- Keep linked filters ahead of saved filters. Preserve unrelated URL
parameters.
- Save preferences per person and company. Keep the controls usable when
storage is unavailable.
- Add selectable Project, Agent, Responsible user, Last run, and Enabled
columns.
- Use play-only manual run buttons with accessible names and pending
indicators.
- Correct the empty message when a status filter excludes every routine.
- Add production-page Storybook examples and browser tests for both
interfaces.

## Verification

- Linux checkout, Node 25.9.0, system Chromium 148.0.7778.96.
- The final change includes master through `07d9316218`. It uses the
shared routine creation form and the upstream Runner test and SDK
source-pin fixes.
- 68 tests pass across eight focused UI suites at `440a9eb6a7`. UI
typecheck, token gates, and whitespace checks pass.
- Two new directory-error cases fail before the fix and pass after it.
Both pages keep routine rows mounted, show an error with Retry, and
restore responsible names after retry.
- 59 checks pass across the SDK source-pin, public-type, and evidence
suites.
- The Runner test program typechecks after building its eval dependency.
A local run of the native-session test file passed 300 tests. One
additional test could not run because the local debug Runner binary was
absent. CI must cover that case.
- Storybook builds and all 13 browser checks pass on
`64a87af7c085426d09eb8aa48bf9491487565990` after the latest master
integration. They cover current and Classic controls, filters, columns,
links, selection alignment, Recent Runs, mobile overflow, and shared
toolbar behavior.
- Storybook examples: Default, LinkedFilters, Classic, ClassicSelection,
and ClassicRuns. They mount production pages with fictional API
responses. Screenshots cover light, dark, filters, custom columns, and
mobile. The baseline manifest has no snapshots; these are visual review
captures.
- Earlier preference, shared-link, title-link, compact-row, and
filter-render-cost regressions have red/green evidence. The
scheduled-routine journey has 17 passing unit checks from the prior
revision.
- The shared selector has three large-list cases with 1,200 routines and
120 folders. All filters are active. Each case checks row order and
folder counts. Work counters throw if filtering repeatedly scans
selected IDs or folder counts scan the routine list for each folder.
Both deliberate regressions fail; the unchanged selector passes. Both
Routines pages use this selector. The latest commit adds only these
tests; production source is unchanged.
- [CI at
`64a87af7c0`](https://github.com/paperclipai/paperclip/actions/runs/44416091562)
passed all jobs, including typecheck, Build, Runner, general tests,
serialized tests, and E2E. [Final-head CI at
`440a9eb6a7`](https://github.com/paperclipai/paperclip/actions/runs/44419144971)
now passes on attempt 2. All 52 executed jobs pass; one file-selection
job is skipped. Typecheck, Build, all test shards, E2E, Runner, and the
aggregate verify gate pass. The first attempt failed in the
timing-sensitive watchdog fixture; its retry passes.
- `pnpm verify` returned exit 2 because this branch needs broad CI
coverage. Final-head CI passes. Greptile and Ponytail both give 5/5 at
`440a9eb6a75184a35001e99a17e6856b7cdb0bd5`. All 20 inline threads are
resolved.
- Prior CI at `10a5b0813b` passed all general and serialized test
shards, all E2E shards, and Build. It failed on a circular test-mock
type and a stale SDK source pin. Master now contains both repairs; the
final branch uses those repairs.
- The two Routines page bodies were already duplicated. This PR reduces
them and shares list data, controls, rows, and view state. Codie owns
the remaining page-shell consolidation as later work.
- Live provider execution and scheduler behavior are outside this
presentation change. Protected Storybook publication still requires a
configured human reviewer; no deployment approval is inferred from merge
authorization.

## Risks

View settings now include filters. A person can return to a filtered
list. The URL and active filter button show that state. Shared filter
URLs override local filters. Column choices stay local. The shared
filter extraction can affect Tasks, so its component and toolbar checks
are included. No migration is needed.

## Model Used

OpenAI GPT-6 through Codex. The runtime does not expose a more specific
model revision. Used reasoning, source editing, shell tools, and browser
automation. No sub-agents were 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
- [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>
canary/v2026.1119.0-canary.829100
2026-11-18 17:43:29 -06:00
Devin FoleyandPaperclip d702f567bc fix(recovery): keep a task's lock while its run's executor still settles it (#22248)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - When an agent's provider account recently reported a usage limit,
Paperclip holds new work instead of starting a run that would fail the
same way. The provider limit wait cancels the run, then schedules a
retry at the expected reset, and the retry takes over the task's
execution lock
> - The cancellation and the retry are two separate writes. Cancelling
the run wakes task recovery for that task, and its stale-lock sweep
treats a cancelled run's lock as stale and clears it
> - When the sweep wins that race, the retry scheduler finds the lock
gone and refuses to schedule ("Subscription retry suppressed because the
task execution lock changed"). The wait then releases the task, and
stranded-work recovery escalates it to a person with a Retry button
> - The stranded-work reconciler already waits while a terminal run's
own executor is still settling it (`terminalRunSettlingUntil`). The
stale-lock sweep did not
> - This pull request makes the stale-lock sweep wait for the same
executor before it clears an open task's lock, and look again at the
executor's deadline
> - The benefit is that a task waiting for a provider usage limit
resumes by itself at the reset, instead of stopping on "Couldn't finish
this attempt" until someone presses Retry

## Linked Issues or Issue Description

Refs #19246, which added the provider usage limit wait.

**What happened?**
An agent's provider account hit a usage limit. A task's next wake was
held for the reset: its run was cancelled with `provider_limit_wait`.
About 200 ms later the stale-lock sweep cleared the task's execution
lock, because the run was now cancelled. The wait then tried to schedule
its retry, found the lock gone, and released the task. The continuation
that followed hit the same race. After two lost retries, stranded-work
recovery blocked the task and asked for Retry.

On one instance, 80 of about 600 provider-limit waits in two days lost
their retry this way, across 43 tasks. 15 of those tasks were blocked
behind a Retry button.

**Steps to reproduce**
1. Give an agent a recent provider rate-limit failure with no reported
reset.
2. Wake the agent on an assigned task.
3. Let task recovery sweep the task's locks between the cancellation and
the retry (the new integration test does this from the cancellation
write).

**Expected behavior**
The task keeps its lock for a retry scheduled at the reset.

**Actual behavior**
The sweep clears the lock, no retry is scheduled, and the task waits for
a manual Retry.

## What Changed

- `recovery/service.ts`: `sweepStaleIssueLocks` keeps an open task's
lock while a run that holds it is still being settled by its executor,
using the existing `terminalRunSettlingUntil`. That is a live execution
in this process, or an unexpired controller lease in another one. The
sweep reports the deadline through `onDeferredDeadline`, so it looks
again once the executor is done. A closed task's lock is still cleared
at once.
- Tests:
- The stale-lock sweep keeps an open task's lock while the executor is
live, and clears it once the executor is gone. A done task's lock is
cleared either way.
- A provider-limit wait whose cancellation is swept straight away still
schedules its retry, and the retry holds the task's lock.

## Verification

- `npx vitest run` on the new cases: pass. Both fail without the source
change; the integration test then reproduces the incident (the sweep
clears the lock and no retry is scheduled).
- `npx vitest run` on 58 related server test files (stale-lock sweep,
stranded and assigned-work recovery, provider limit wait, native resume
locks, retry admission, recovery hints): all pass, except 6 cases in
`runtime-selection.test.ts` that read a skill file from a fixed local
path. They fail the same way on master on this machine.
- `npx tsc --noEmit` passes for the server.

## Risks

- Low. The sweep waits only while the run's executor is provably still
running: a live execution in this process, or another process's
unexpired controller lease. A crashed executor has neither, so the sweep
clears the lock as before.
- An executor that keeps running after its run is terminal now delays
the sweep's backstop clear of an open task until it finishes. The
executor releases or hands off the lock itself when it finishes, and the
stranded-work reconciler already waits for the same executor.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution
in Claude Code.

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-18 15:39:14 -08:00
DottaandClaude Opus 5.5 28bdb4d778 feat(cloud): migrate durable data online and name volume-free config blockers (#22240)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Hosted Paperclip servers can move from a server with a volume to a
volume-free server, which allows deploys without downtime
> - A server with history can move online only after its durable data is
off the local disk
> - Today only an offline maintenance process moves that data, so each
existing server takes an outage of many minutes
> - Most data owners already work safely while the server keeps serving,
but nothing drives them online
> - This pull request adds a signed, bounded pass that drives those
owners online and reports progress, and it names configuration blockers
> - The benefit is that existing servers can move to volume-free with no
maintenance window

## Linked Issues or Issue Description

**What existing behavior does this improve?**
An existing volume-backed server can move to volume-free only through
offline maintenance, because only the offline process migrates its local
data.

**Subsystem affected**
Server: ephemeral enrollment, durable data owners (agent files, skill
packages and installations, runtime skill assets, native harness backups
and controllers), Cloud control endpoints.

**Current behavior**
- Online preparation refuses while local data remains, and no online
path moves that data.
- When the volume-free configuration is incomplete, preparation fails
with a server error that does not say why.

**Proposed behavior**
- `POST /api/instance/ephemeral-enrollment/migrate` (Cloud control
action `ephemeral-enrollment:migrate`) runs one pass with a 60-second
budget. The pass drives the online-safe owners, defers items that are
busy, and returns counts, deferral reasons and fresh eligibility.
- Preparation and the eligibility read report an incomplete
configuration as a named blocker: `volume_free_storage_flags_required`,
`volume_free_master_key_required`, `volume_free_decision_key_required`,
`volume_free_database_listener_required` or
`volume_free_configuration_required`. Preparation returns 409 with these
blockers.

**Reason and benefit**
Cloud can call the pass until a server is eligible, and then move it
online with no outage.

**Breaking changes**
None. The offline maintenance behavior is unchanged.

## What Changed

- New `services/online-durable-data-migration.ts`. The pass:
- requires S3 storage and `PAPERCLIP_DURABLE_AGENT_FILES=true`, so the
server does not keep creating local data;
- runs these owners in order, with live writers: `migrateAgentFiles`
(`writersStopped: false`), the local skill object copy, skill snapshots
and versions, skill installations, runtime skill assets, and the native
harness and controller prestage;
  - stops between pages when the budget is spent;
  - runs one pass at a time in each process.
- `skill-package-storage-migration.ts`: a new `online` mode. In this
mode a row that another owner holds is skipped and counted as `busy`.
The row claim and the publication already use compare-and-swap. The
offline mode is unchanged and still fails closed on a busy row.
- `services/ephemeral-enrollment.ts`: a configuration check maps the
volume-free contract errors to blocker codes. Preparation and the
eligibility read both use this check.
- `routes/ephemeral-enrollment.ts`, `middleware/cloud-control.ts`,
`services/cloud-runtime-identity.ts`: the new route and action. The
route accepts only an empty body.

## Verification

- `npx vitest run src/routes/ephemeral-enrollment.test.ts
src/services/ephemeral-enrollment.test.ts
src/services/online-durable-data-migration.test.ts
src/services/skill-package-storage-migration.test.ts
src/__tests__/openapi-routes.test.ts
src/services/cloud-runtime-identity.test.ts`: 102/102 pass.
- New tests:
- the pass drives every owner with live writers, aggregates counts and
deferrals, and reports eligibility;
  - the pass does nothing without S3 or durable agent files;
  - the pass stops at the budget;
  - one pass runs at a time;
- the skill object copy refuses outside maintenance unless the mode is
online, skips a busy row online, and still fails closed offline;
- each missing setting becomes a named blocker in preparation and in the
eligibility read;
- the migrate route accepts only a signed migrate assertion and an empty
body.
- `tsc --noEmit` reports no errors in the touched files. A full local
`pnpm verify` needs the Runner build, so CI covers it.

## Risks

- The pass runs real migrations while the server serves. Each owner
keeps its own locks and compare-and-swap rules. Busy items are deferred,
not forced. The budget limits each call.
- The skill object copy can now run online. It copies immutable objects,
verifies the hashes, and publishes only if the row did not change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, browser).

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 17:36:30 -06:00
DottaandClaude Opus 5.5 45c3f4caa2 fix(connectors): require an install before an agent reaches a plugin connector (#22237)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Plugins can add connectors that serve their own tools (`transport:
"plugin"`, #22004, #22019, #22201)
> - The activation rule is that an agent gets a connector's tools only
through an install of an active connection for that agent
> - An agent with no install could still list and call a plugin
connector's tools, and the plugin worker ran them with that agent's run
context
> - This pull request makes the tool access policy require the install
for plugin-served connections
> - The benefit is that a plugin connector reaches only the agents it is
installed for

## Linked Issues or Issue Description

Refs #22004
Refs #22019
Refs #22201

**Subsystem affected**
Tool access policy and tool gateway (plugin-served connectors).

**Problem or motivation**
A plugin connection was installed for agent A only. Agent B, a standard
agent with no install, called one of its tools. The plugin worker got a
run context with B's agent id.

**Root cause**
An install gives access only through the connection's app profile
binding. The policy does not check installs. For an agent outside that
profile, the policy goes on to its other allow routes. The common route
is the unscoped `tools:use` grant that every new standard agent receives
(`NEW_STANDARD_AGENT_DEFAULT_GRANT_KEYS`). `governedByConnectionProfile`
is false for B, because B is not bound to the connection's profile. So
`explicitGrant` allowed the tool for discovery and invocation.
Organization-grant connections ran the worker. Per-agent connections
listed the tools and reached grant resolution.

**Expected behavior**
An agent without an install for the connection (or a company install)
sees no tools and cannot call them. An installed agent is not affected.

## What Changed

- `server/src/services/tool-access-policy.ts`: for an agent caller on a
connection whose stored transport is `plugin`, deny with the new reason
`deny_connection_not_installed` unless an install exists for that agent
or the company. The check runs before profiles, grants, trust rules and
allow policies, so none of them can replace the install. It reads the
transport from the stored connection, not from the caller. The install
read uses the decision cache, so a listing batch reads it once per
connection.
- `packages/shared/src/types/tool-access.ts`: add
`deny_connection_not_installed` to `ToolAccessReasonCode`.
- `doc/connections/CONNECTOR-PLAYBOOK.md`: document the rule.
- Legacy plugin tools (`paperclip_plugin`) keep their own
implicit-install gate and are not changed.

## Verification

- New `server/src/__tests__/plugin-connector-install-gate.test.ts`
(embedded Postgres, real routes). Both agents get the default
standard-agent grants, including the unscoped `tools:use`. For an
organization-grant connection and a per-agent connection installed for A
only:
- A lists the tool through its gateway session and its Paperclip Runner
assigned-tool gateway, and a call reaches the worker.
- B (with its own install of an unrelated connection) lists none of them
in either path.
- B's direct call by name through its gateway session, its runner
gateway, and the runner's `paperclip_call_assigned_tool` is refused. The
worker is never called.
  - Before the fix, both cases failed: B listed the tool.
- Regression suites pass: `tool-access-policy-service`,
`tool-access-policy-index`, `tool-gateway`, `tool-gateway-service`,
`tool-gateway-*`, `prompt-injection-gateway`,
`plugin-connectors-plugin-transport` (legacy plugin tools),
`plugin-connectors-circleback-parity`, `plugin-connector-agent-grant`,
`heartbeat-runtime-mcp-servers`, `run-preparation`,
`tool-access-service`, `generic-mcp-connection`,
`remote-mcp-connectors`, `railway-connection`, `aws-mcp-connector`,
`mcp-protocol-versions`, `google-workspace-*`.
- `tsc --noEmit` passes for `server`, `packages/shared` and `ui` source.

## Risks

- Behavior change: an uninstalled agent loses access to plugin-served
connection tools it reached before through a general grant, a trust rule
or an allow policy. That access broke the activation rule. Installed
agents and company installs are not affected.
- The board's per-agent access check now shows
`deny_connection_not_installed` for agents without an install.
- Built-in (non-plugin) connections are not changed by this pull
request. They have the same policy path. Whether to require installs for
them is a separate decision, because existing setups may depend on it.
- No migration.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, test runs).

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 17:34:09 -06:00
85a1e5f940 docs(release): canonicalize stable notes for v2026.1117.0 (#22247)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The release process promotes a soaked beta to stable and publishes
the curated notes as the GitHub Release body
> - After the publish, the notes must live at
`releases/v<stable-version>.md` on `master`. That path is the canonical
location that the website changelog and the next release notes use
> - Stable `v2026.1117.0` was published on 2026-11-18 from beta
`2026.1110.0-beta.0`, through the candidate branch
`candidate/release-2026.1117.0` (the beta source plus three test-only
cherry-picks and the notes file)
> - Because the notes resolved from the source tree
(`notes_mode=source_tree`), the workflow's `canonicalize_stable_notes`
job is skipped by design (it runs only for `master_beta`), so no
canonicalize branch was pushed
> - This pull request does by hand what that job does: it renames the
beta notes file on `master` to the stable path. It changes no content
> - The benefit is that `releases/v2026.1117.0.md` exists on `master`
and is byte-identical to the published GitHub Release body

## Linked Issues or Issue Description

Refs #22094
Refs #19770

**Issue type**

Missing content

**Where is the issue?**

`releases/` on `master`. The stable notes for `v2026.1117.0` are only at
the beta path `releases/beta/v2026.1110.0-beta.0.md`. The canonical path
`releases/v2026.1117.0.md` does not exist on `master`.

**What's wrong?**

The GitHub Release
https://github.com/paperclipai/paperclip/releases/tag/v2026.1117.0 is
published. The website changelog sync reads `releases/v2026.1117.0.md`
on `master`, so the changelog page for this release cannot appear until
this rename is merged.

**Suggested fix**

Rename the beta notes file to the stable path with no content change,
the same step the workflow job performs in `master_beta` mode.

## What Changed

- `releases/beta/v2026.1110.0-beta.0.md` is renamed to
`releases/v2026.1117.0.md`. Git reports a 100% rename
- No line of the file changes. The blob is
`dff612e41f915a5a2d9f3e572142e2fee56068a8`, the same blob as
`releases/v2026.1117.0.md` at the release source commit
`c0f132898d2a2677312d8c72096187b27a3d9a38` (tag `v2026.1117.0`)
- This pull request does not change the release workflow

## Verification

- `git diff --numstat -M origin/master
release-notes/v2026.1117.0-canonicalize` shows one renamed file with 0
insertions and 0 deletions
- `git rev-parse
release-notes/v2026.1117.0-canonicalize:releases/v2026.1117.0.md` prints
`dff612e41f915a5a2d9f3e572142e2fee56068a8`
- `git rev-parse v2026.1117.0:releases/v2026.1117.0.md` prints the same
blob
- The raw `body` field of `gh api
repos/paperclipai/paperclip/releases/tags/v2026.1117.0`, compared with
`cmp` against the file, reports no difference
- After merge,
https://github.com/paperclipai/paperclip/blob/master/releases/v2026.1117.0.md
should return 200 and the old beta path 404

## Risks

- Low risk: one markdown file moves and no content changes

## Model Used

- Claude (Anthropic), model ID `claude-opus-5-5` (Claude Opus 5.5), tool
use via Claude Code

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:26:53 -08:00
DottaandClaude Opus 5.5 d1ca0cc218 fix(native): stop retrying a run that filled its sandbox disk (#22239)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Native agent runs execute in a managed sandbox with a fixed disk
size
> - An agent can fill that disk. The runner then exits with "No space
left on device". The disk reserve restarts the runner, but the turn in
progress can still be lost, and the run fails
> - The run failure did not carry the full-disk fact. The run was
classified as a generic provider or runner failure. Automatic recovery
then started the same work on a fresh sandbox of the same size, which
filled the disk again. After three attempts the task stopped in
"Recovery needed" with no useful explanation
> - This pull request names the cause `sandbox_disk_full` when the
runner reported a full disk during the run, and stops automatic retries
for that cause
> - The benefit is that Paperclip no longer spends sandboxes and time on
retries that cannot succeed, and the task tells the user what to do in
plain language

## Linked Issues or Issue Description

**What happened?**
A native run in a managed sandbox filled the 10 GiB disk. The runner
exited with "No space left on device (os error 28)". The runner was
restored, but the in-flight turn was lost and the run failed as
`native_provider_terminal_failed`. Automatic recovery repeated the same
work on a fresh sandbox of the same size three times. Each attempt
filled the disk again. The task ended in "Recovery needed" with an
unrelated cause.

**Expected behavior**
When a run ends because its sandbox disk is full, the run failure names
that cause. Automatic recovery does not repeat the same work on a
sandbox of the same size. The task shows a plain-language explanation
and a working Retry.

**Steps to reproduce**
1. Run a native agent task in a managed sandbox whose work installs more
than the free disk space.
2. Wait until the runner exits with "No space left on device".
3. See the run fail as a generic provider failure, and see automatic
retries start fresh sandboxes that fail the same way.

**Relevant logs or output**
`paperclip-runner` exited with "No space left on device (os error 28)".
The run then failed with `provider_turn_lost_on_restore`, classified as
`native_provider_terminal_failed`.

Refs #22068 (disk reserve that restarts the runner). Refs #22235
(continues a turn that a runner restore lost, once, in the same
sandbox). This PR covers the case where the run still ends.

## What Changed

- Server: each run's diagnostic lease now records when a runner
diagnostic reports a full disk (`ENOSPC`, `EDQUOT`, "No space left on
device", "Disk quota exceeded"). The runner's exit detail already
reaches the server as a diagnostic, so no runner change is needed. The
fact belongs to that run's diagnostic epoch only. A later run on the
same warm session, or a diagnostic after the epoch retires, does not see
it.
- Server: native failure classification returns `sandbox_disk_full` when
either (a) the run's lease saw a full-disk report, or (b) the error
chain carries the runner's existing `sandbox_disk_full` launch code (a
relaunch that cannot stage on the full disk). A fixed list of failures
keeps its own meaning: permission, approval, usage limit, model,
runtime, integrity, cleanup quarantine, ownership, saved-state and
admission failures.
- Server: `sandbox_disk_full` is a permanent native failure. The run
does not take another same-run attempt. Native safe replacement does not
pick it up, because it is not one of its failure codes. The task becomes
blocked with a board-owned recovery action and a plain-language next
action.
- Server: the bounded retry scheduler (`scheduleBoundedRetryForRun`)
refuses `sandbox_disk_full`. It does not schedule a `transient_failure`
retry on a fresh sandbox of the same size.
- UI: the task chat shows "Disk full" and a plain explanation instead of
the raw failure code.
- Retry stays available. `sandbox_disk_full` is not a reconciliation
cause, so the board's Retry starts a new run when the user chooses.

## Verification

- Red before the fix (captured on the unfixed code):
- `heartbeat-retry-scheduling.test.ts` "does not repeat a run that
filled its sandbox disk on a fresh sandbox of the same size": expected
`not_scheduled`, received `scheduled`.
- `native-sandbox-disk-full.test.ts` "names the full disk and stops
instead of retrying the same work": expected `sandbox_disk_full`,
received `native_provider_terminal_failed`.
- `native-sandbox-disk-full.test.ts` "names the full disk when the
runner could not be relaunched on it": expected `sandbox_disk_full`,
received `native_session_interrupted`.
- Green after the fix:
- `cd server && npx vitest run
src/services/native-runtime/native-sandbox-disk-full.test.ts
src/__tests__/heartbeat-retry-scheduling.test.ts
src/services/native-runtime/remote-runner-disk-reserve.test.ts` (90
passed).
- `cd ui && npx vitest run src/components/TaskChatThread.test.tsx` (426
passed).
- `cd server && npx vitest run
src/services/native-runtime/native-session-executor.test.ts
src/services/native-runtime/native-session-diagnostics.test.ts`.
- Safety cases in the tests:
- A runner that exited for another reason still gets its bounded retry.
- A turn lost on restore without a full-disk report keeps
`native_provider_terminal_failed`.
- Integrity and approval failures keep their codes when a full disk was
reported.
- A full-disk report belongs only to its own run's diagnostic epoch; run
B on the same session does not see run A's report.
- After a full-disk report, other runner and provider loss codes
(session.open timeout, initialize timeout, protocol error, process
status failure) also become `sandbox_disk_full`.
- Worst-case automatic run starts per hour across a company: before,
each disk-full task started up to 3 automatic runs, each on a fresh
sandbox (3 × the number of affected tasks). After, a disk-full failure
starts 0 automatic runs. Only a person's Retry starts a new run. Real
transient failures keep their existing bounded lanes, so their worst
case is unchanged.
- Not run locally: the full server suite, the full typecheck and build.
Required CI covers them.
- Not verified live on staging yet. A live check needs a run that fills
its sandbox disk after this change deploys.

## Risks

- A run whose runner reported a full disk, and which later fails with a
runner or provider loss for an unrelated reason, is now labeled
`sandbox_disk_full` and is not retried automatically. The board's Retry
still works. This is the safer error: a full disk is the most likely
cause, and an automatic retry would repeat the same disk use.
- The full-disk report lives on the run's in-memory diagnostic lease. A
server restart between the report and the failure loses it, and the run
falls back to the previous classification. That is the previous
behavior, not a new failure.
- Low risk otherwise. No schema or API change.

> 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

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with
tool use (shell, file edits, test runs).

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 23:19:12 +00:00
DottaandClaude Opus 5.5 07d9316218 fix: restore master's typecheck and runner SDK input pin (#22242)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - #22235 added a runner regression test for a turn lost to a mid-run
`runnerd` restore
> - That test reads `startTurn.mock` inside the initializer of
`startTurn` itself
> - The CI test-program typecheck rejects this with TS7022 and TS7024,
so master fails "Typecheck + Release Registry"
> - This pull request counts calls in a local variable instead
> - The benefit is that master typechecks again, and the test behaves
exactly as before

## Linked Issues or Issue Description

Refs #22235, Refs #22234

**What happened?**
After #22235 merged, `ci / Typecheck + Release Registry` failed on
`packages/paperclip-runner/src/native-session-runtime.test.ts(724)` with
TS7022 ("'startTurn' implicitly has type 'any'...") and TS7024.

**Steps to reproduce**
1. Run the CI typecheck lane (`typecheck test programs`) on master after
#22235.
2. See TS7022 and TS7024 at line 724 of the test.

**Expected behavior**
The test program typechecks.

## What Changed

- The `startTurn` mock in the new test uses a local call counter instead
of reading its own `mock.calls`.
- `tests/runner-e2e/source-sdk-public-inputs.json`: refresh the pin for
`packages/shared/src/app-definitions/github.json`, which #22234 changed
without updating it. The Runner support suite fails on master without
this.

## Verification

- `npx tsc -p packages/paperclip-runner/tsconfig.test.json --noEmit`
reports no errors in the test file.
- `npx vitest run src/native-session-runtime.test.ts` in
`packages/paperclip-runner`: 301/301 pass.

## Risks

- Low risk. This changes a test and regenerates a pin with the
repository script (`node tests/runner-e2e/source-sdk-public-inputs.mjs
<sha> --write`). `source-sdk-public-inputs.test.mjs`: 13/13 pass.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with 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
- [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: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 16:49:12 -06:00
eaac8ed0f7 feat(adapters): add Claude Fable 5.2 and GPT-6.2 with CLI floors, and refresh sandbox CLI pins (Nov 18 audit) (#22222)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents run on coding harnesses. Each adapter has a model catalog,
and sandboxes contain pinned CLIs.
> - Anthropic released Claude Fable 5.2 and OpenAI released GPT-6.2 Sol
and GPT-6.2 Astra for Codex. Both need newer CLIs than the Paperclip
Runner provider pack ships.
> - A stale catalog hides valid models. A model that needs a newer CLI
fails with an opaque backend error.
> - This pull request adds the verified model IDs with their CLI floors,
names the version gap in Paperclip Runner, and refreshes the sandbox CLI
pins.
> - The benefit is that operators can select current models and get a
named version error instead of a backend failure.

## Linked Issues or Issue Description

Refs #20774 and #21636 (both add parts of Fable 5.2 support; see
"Overlap" below).
Refs #18486 (adds GPT-6.1 Terra; this PR does not duplicate it).
Refs #16708 (adds Claude Haiku 5.5 to `claude_local`; this PR does not
duplicate it).

**What happened?**

Claude Fable 5.2 (`claude-fable-5-2`) and GPT-6.2 Sol / Astra
(`gpt-6.2-sol`, `gpt-6.2-astra`) are generally available. The
`claude_local`, `codex_local`, and OpenCode pickers do not list them.
Claude Code 2.1.321 is the first release with Fable 5.2. Codex 0.169.1
is the first release whose bundled catalog lists GPT-6.2. The Paperclip
Runner provider pack bundles Claude Code 2.1.286 and Codex 0.160.0.

**Expected behavior**

The pickers list the new models. A run on a CLI below the model minimum
stops with the detected and required versions, or falls back to a
compatible model with a visible message.

**Proposed change**

Add the models and their per-model CLI floors. Gate ACPX Claude in
Paperclip Runner on the Claude Code version that its Agent SDK bundles.
Refresh the sandbox CLI pins with verified digests. Record the audit.

## What Changed

- Claude Code (`claude_local`):
- Add `claude-fable-5-2` (label "Claude Fable 5.2") at the top of the
picker. `claude-fable-5-1` stays selectable after the current-generation
models.
- Add Bedrock `global.anthropic.claude-fable-5-2`. Anthropic documents
only this global ID for Bedrock.
  - Fable 5.2 offers all five efforts (`low` to `max`).
- `minimumClaudeCliVersionForModel("claude-fable-5-2")` returns
`2.1.321`. The existing CLI-lane Test and launch checks use this floor.
On a managed sandbox, the CLI lane installs a private Claude Code at
this version, as it does for the other floors.
- Paperclip Runner (ACPX Codex): `resolvePaperclipRunnerProviderProfile`
rejects a model whose Codex floor is above the qualified ACPX Codex
runtime (`0.160.0`). The error code is
`paperclip_runner_codex_cli_version_incompatible`, and the message gives
both versions.
- Paperclip Runner (ACPX Claude):
`resolvePaperclipRunnerProviderProfile` rejects a model whose Claude
Code floor is above the version that the qualified Agent SDK bundles.
The error code is `paperclip_runner_claude_cli_version_incompatible`.
The message gives both versions. A new helper,
`claudeCodeVersionForAgentSdk`, maps SDK `0.3.N` to Claude Code `2.1.N`
(the SDK's `claudeCodeVersion` field) and returns `null` for any other
line.
- Codex (`codex_local`):
- Add `gpt-6.2-sol` and `gpt-6.2-astra` at the top of the picker, in the
bundled catalog order.
  - Both offer Fast mode and the `low` to `ultra` efforts.
- Both have a CLI floor of `0.169.1`. On the native Codex provider with
the pinned Codex 0.160.0, the existing fallback moves `gpt-6.2-sol` to
`gpt-6.1-sol` and `gpt-6.2-astra` to `gpt-6-astra` with a visible
message.
  - The default stays `gpt-6.1-sol`.
- OpenCode fallback catalog: add `openai/gpt-6.2-sol`,
`openai/gpt-6.2-astra`, `anthropic/claude-fable-5-2`,
`google/gemini-4-carbon`, and `google/gemini-4-hydrogen`.
- Evaluation image sandbox layer (`docker/daytona-runner`):

  | CLI | Before | After |
  | --- | --- | --- |
  | Grok CLI | 1.0.70 | 1.0.89 |
  | Gemini CLI | 0.65.0 | 0.68.0 |
  | Cursor CLI | 2026.10.22-27dcf5f | 2026.11.17-f532c45 |
  | GitHub CLI | 2.103.3 | 2.105.0 |

- Add `doc/adapter-model-audit-2026-11-18.md` with sources,
compatibility findings, and deferred items. Add a note on above-window
Codex floors to `doc/architecture/paperclip-runner-compatibility.md`.

No saved agent changes model, effort, or spending settings. No picker
entry is removed.

### Managed sandboxes

On Paperclip Runner, Fable 5.2 and GPT-6.2 stay unusable until the
provider pack moves to Claude Code 2.1.321 or later and Codex 0.169.1 or
later. A sandbox image that carries that provider pack must also be
promoted. This PR does not change the provider pack (see "Deferred
items" in the audit). Native remote Codex accepts only `>=0.149.0
<0.161.0`, so GPT-6.2 also needs that window to move.

### Overlap

- #21636 sets the Fable 5.2 floor to `2.1.290`. The [Claude Code
changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
adds Fable 5.2 in 2.1.321. `git merge-tree` merges the two without a
text conflict, but #21636's line becomes unreachable after this PR's
line, and its test then fails. Rule: keep `2.1.321`. Merge this PR
first. Then close #21636 or change its floor and test to `2.1.321`.
- #20774 (draft) lists `claude-fable-5-2`. It conflicts in
`packages/adapters/claude-local/src/index.ts` and
`server/src/__tests__/adapter-models.test.ts`. Rule: keep this PR's
catalog order and Bedrock ID.
- #18486 adds `gpt-6.1-terra`. It conflicts in
`packages/adapters/codex-local/src/index.test.ts` and
`src/server/codex-args.test.ts` (the ordered ID list and the Fast-mode
message). Rule: keep both sets of models in the bundled catalog order
(`gpt-6.2-sol`, `gpt-6.2-astra`, `gpt-6-astra`, `gpt-6.1-sol`,
`gpt-6.1-terra`, ...). Either PR can merge first; the second rebases.
- #16708 adds Claude Haiku 5.5. It conflicts in
`packages/adapters/claude-local/src/index.test.ts` (adjacent test cases)
and `doc/DEVELOPING.md`. Rule: keep both test blocks.

## Verification

Research date: November 18, 2026. Sources are listed in the audit doc.

- `vitest run src/index.test.ts src/server/model-order.test.ts
src/server/cli-capabilities.test.ts src/server/test.remote.test.ts` in
`packages/adapters/claude-local`: 40 passed. `execute.remote.test.ts`
(29), `test.probe.test.ts` (21), `sandbox-cli-version.test.ts` (15),
`acp.auth.test.ts` (25), and `acp.test.ts` (47, with
`--testTimeout=60000`) also passed when run one file at a time.
- `vitest run src/index.test.ts src/server/codex-args.test.ts
src/ui/build-config.test.ts src/server/test.remote.test.ts` in
`packages/adapters/codex-local`: all passed (155). `acp.test.ts` (49),
`acp.cli-version.test.ts` (4), and `execute.test.ts` (10) also passed
one file at a time.
- `vitest run` in `packages/adapters/opencode-local`: 94 passed.
- `vitest run src/services/native-runtime/acpx-qualification.test.ts
src/services/native-runtime/codex-model-fallback.test.ts
src/__tests__/adapter-models.test.ts
src/__tests__/heartbeat-model-fallback-warning.test.ts` in `server`: all
passed. The new cases cover the ACPX Claude and ACPX Codex version
errors and the native GPT-6.2 fallback on Codex 0.160.0.
- `vitest run src/lib/agent-setup-fields.test.ts
src/lib/codex-reasoning-effort.test.ts` in `ui`: 11 passed.
- `tsc --noEmit` in the three adapters and `pnpm typecheck` in `server`:
passed.
- Cursor archive SHA-256
`189ed41d8963cd22dcdafbbd62f072cc55ac08374c922dbd04aee525f4018ab6` is
computed from the versioned Linux x64 tarball. The extracted binary
reports `2026.11.17-f532c45`, the version that
`https://cursor.com/install` resolves.
- GitHub CLI SHA-256
`79e7ab5db738c48777b696e374f8b428f0647debfb424f44d2f426370407fe2f`
matches `gh_2.105.0_checksums.txt`.
- Grok CLI 1.0.89 and Gemini CLI 0.68.0 installed from npm report those
versions. The flags that Paperclip uses are in `--help` (`-m`,
`--effort`, `grok models`; `-m`, `-p`, `--output-format`,
`--approval-mode`, `--yolo`).
- Host baseline: tests that create an AI provider need the host's empty
`ANTHROPIC_BASE_URL` unset. Under full-package parallel runs, SSH and
sandbox fixture tests time out at 5 seconds on this host; each file
passes alone. The audit doc records both.
- Not run locally: the full `pnpm -r typecheck`, `pnpm build`, browser
suites, and the image build. CI runs these. No live model inference ran.

## Risks

- Low risk for saved agents: no default, saved model, effort, or
spending setting changes.
- The new Paperclip Runner checks reject `claude-fable-5-2` on ACPX
Claude and `gpt-6.2-*` on ACPX Codex (and any later model whose floor is
above the bundled runtime) before launch. Without this PR, the turn
would start and fail at the backend.
- The `0.3.N` → `2.1.N` mapping covers only the current SDK line. Any
other line returns `null`, and the check is skipped.
- The sandbox CLI pins change only the evaluation image. The fleet image
change is separate.
- Rollback: revert this PR. No data migration.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, through Claude Code
with tool use (shell, web fetch, file edits).

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: devinfoley <139239+devinfoley@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 14:27:00 -08:00
Devin FoleyandPaperclip e4b119440e Show live provider reset countdowns in the viewer's timezone (#22225)
## Thinking Path

> - Paperclip manages agents and their assigned work.
> - Provider usage limits can hold that work until a reset deadline.
> - Saved wait messages expose raw timestamps, and the usage popover
shows a short weekday clock.
> - People need the remaining wait and the exact deadline in their
current timezone.
> - This pull request formats both views in the browser and updates the
countdown live.
> - The browser uses its timezone while stored messages and retry
deadlines stay unchanged.

## Linked Issues or Issue Description

**What existing behavior does this improve?**
Provider usage limit messages and the agent usage-limit property and
popover.

**Subsystem affected**
UI presentation of provider usage limits, task notices, run details, log
events, and recovery actions.

**Current behavior**
Wait messages print `2026-11-18T20:17:34.353Z`. The usage popover shows
a short clock such as `Thu 23:00`. Neither gives a live relative
countdown. If the provider did not report a reset, the scheduler uses
the recorded failure time plus one hour.

**Proposed behavior**
A Pacific-time viewer sees `in 44 minutes (Nov 18, 2026, 12:17 PM PST)`.
The relative part counts down while the tab is visible. The usage
property and popover show the same local deadline. Expired usage windows
clear through the existing summary rules.

**Reason and benefit**
People can see how long remains without converting a timestamp or
refreshing the page. The date conversion handles daylight saving time
and local date changes.

**Breaking changes**
Displayed text and popover layout change. Stored messages, API payloads,
error codes, provider checks, and retry deadlines keep their contracts.

## What Changed

- Add an optional timezone label to the existing `formatDateTime`
helper. Existing callers keep their output.
- Share relative and exact local time formatting between provider-limit
messages and the usage popover. Unrelated text and invalid timestamps
stay intact.
- Reuse the existing shared one-second ticker. Countdown updates pause
in hidden tabs, catch up when shown, and stop at the deadline or on
unmount. No API polling is added.
- Keep timer-driven message rendering separate from large parent pages.
Hidden task-marker details do not subscribe until opened.
- Update task notices, agent run errors in both UI shells, log events,
and provider-limit next actions.
- Update the usage-limit trigger and every window in its popover. Reset
details wrap below the percentage row. The reported timestamp includes
its timezone. Explicit clocks remain fixed for stories.

## Verification

Tested source: `ef79ce40b170db89a6b831162c72d6446cd9492d`. Local checks
ran with the same file contents on macOS arm64, Node 25.6.1, and pnpm
9.15.4.

- From `ui/`: `pnpm exec vitest run
src/lib/provider-limit-message.test.ts src/lib/utils.date-time.test.ts
src/components/ProviderLimitMessage.test.tsx
src/hooks/useSecondTick.test.tsx
src/components/AgentRateLimitGauge.test.tsx
src/components/task-chat/TaskChatMarker.test.tsx
src/components/task-chat/TaskChatSystemNotice.test.tsx
src/components/IssueRunLedger.test.tsx
src/components/IssueRecoveryActionCard.test.tsx
src/components/StalledDependencyNotice.test.tsx
src/pages/AgentDetail.log-visibility.test.tsx
src/pages/AgentDetail.log-resilience.test.tsx` — 176 tests passed across
12 files.
- From `ui/`: `pnpm run typecheck` — passed, including Storybook catalog
generation.
- From the repository root: `pnpm check:token-gates` and `git diff
--check` — passed.
- Regression proof: four live-message cases failed against static
rendering. Four usage-popover cases failed against the old clock. Both
suites passed after the changes.
- Fake-clock tests prove `44 minutes` becomes `43 minutes` without a
page refresh or parent render. Other cases cover seconds near the
deadline, one shared timer, hidden-tab pause and catch-up, expiry, and
cleanup.
- Timezone cases cover Pacific, India, and New Zealand timezones, a
local date rollover, and daylight saving time. Task notice cases cover
both presentations. Usage-popover cases cover Claude and Codex.
- Local setup required a non-frozen install because the base lockfile
lacked two AWS SDK dependencies from the server manifest. No dependency
or lockfile change is included.
- Final CI: [workflow attempt
4](https://github.com/paperclipai/paperclip/actions/runs/44384225521/attempts/4)
succeeded on `ef79ce40b170db89a6b831162c72d6446cd9492d`. All 54
successful checks are green, including the applicable typecheck, build,
server tests, Runner checks, and all eight end-to-end shards. Optional
jobs skipped by the CI plan remain skipped.
- Recovery record: [Canary attempt
1](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135085343566),
[attempt
2](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135097010510),
and [attempt
3](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135100921795)
ended with runner shutdown signals at 19:56:15, 20:12:55, and 20:19:18
UTC. The aggregate verification failures reflected that canary result.
No source changed between attempts. The [fourth Canary Dry
Run](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135105826026)
and [aggregate
verification](https://github.com/paperclipai/paperclip/actions/runs/44384225521/job/135110708013)
passed.
- Greptile reviewed the final commit at 5/5 with no actionable findings
and no unresolved review threads. GitHub reports the branch mergeable
with a clean merge state.
- Full local repository checks and manual browser acceptance were not
run. CI supplied broad coverage on the final revision. The local popover
tests exercise its content and clock with mocked popover primitives.

## Risks

- Low risk. This changes UI presentation only. No migration or scheduler
change is required.
- The ticker updates visible future countdowns once per second. It makes
no provider request and does not certify that provider capacity has
returned.
- Message recognition uses the existing provider-limit wording and ISO
timestamps. Unrecognized messages retain their text.
- Local timezone abbreviations can differ by browser locale data. Time
conversion uses the browser's timezone rules.

## Model Used

- OpenAI Codex, `gpt-6.1-sol`, with xhigh reasoning effort, repository
inspection, code edits, and test 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
- [x] I have described the issue in-PR with the enhancement template
fields
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
ticket id
- [x] I have run the focused tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] The code, tests, and this description document the changed output
- [x] I have considered and documented the risks
- [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>
2026-11-18 14:19:17 -08:00
DottaandClaude Opus 5.5 d668eeb660 fix(runner): keep Claude MCP bearer tokens out of process arguments (#22206)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - The runner starts Claude through ACPX and the Claude ACP agent.
> - The runner gives Claude HTTP MCP servers: the task tool bridge and hosted connectors. Each server has a bearer token.
> - The Claude Agent SDK writes these servers, with their headers, into the inline `--mcp-config` argument of the Claude CLI.
> - Thus a `ps aux` or `ps -ef` command in the sandbox shows the bearer tokens. Tool logs then keep the tokens.
> - This pull request sends a `${VAR}` reference in the header. The token goes into the launch environment of the agent.
> - The benefit is that process lists do not show MCP bearer tokens.

## Linked Issues or Issue Description

**What happened?**
An agent ran `ps aux` in its sandbox. The output showed the Claude CLI process with an `--mcp-config` argument. That argument had an `Authorization: Bearer <token>` header for each HTTP MCP server. The tool log kept the full output.

**What did you expect to happen?**
Process arguments must not contain credentials. A process list must not show MCP bearer tokens.

**Steps to reproduce**
1. Start a Claude agent on the runner with the task tool bridge or a hosted connector.
2. In the agent, run `ps -ef`.
3. Look at the Claude CLI line. The `--mcp-config` JSON contains `"Authorization":"Bearer ..."`.

**Root cause**
`openQualifiedAcpxRuntime` sent the literal `Bearer <token>` header in the ACP `mcpServers` list. The Claude ACP agent gives this list to the Claude Agent SDK. The SDK always serializes it into `--mcp-config <json>` on the CLI command line.

## What Changed

- For the Claude ACPX profile, each HTTP MCP header now has the value `Bearer ${PAPERCLIP_ACPX_MCP_BEARER_<n>}`.
- The runner puts each token in the Claude launch environment under the same name. Claude Code expands `${VAR}` in `--mcp-config` when it connects to the server.
- Other ACPX agents keep the literal header. Their CLIs do not have a known `${VAR}` expansion.
- Added a regression test. Updated one exact launch-environment assertion for the new variable.

## Verification

- Failing before the fix: `npx vitest run src/drivers/acpx/acpx-runtime-adapter.test.ts -t "MCP bearer tokens out of the CLI argv"` (in `packages/paperclip-runner`). It failed with `expected '[{"type":"http","name":"paperclip",…' not to contain 'bridge-secret'`. The projected header had the literal synthetic token.
- Passing after the fix: `npx vitest run src/drivers/acpx/acpx-runtime-adapter` — 7 files, 136 tests passed.
- Manual check of the expansion: I ran the pinned Claude CLI (agent SDK 0.3.286) with `--mcp-config` and a header `Bearer ${SYNTH_MCP_BEARER}` against a local HTTP server. The server got the expanded synthetic value.
- `tsc --noEmit -p packages/paperclip-runner`: no new errors. The only errors are in `src/eval/workflow-harness.ts` and occur on `master` too, because my local install did not include the eval kernel package.
- The full `src/drivers/acpx/` folder has other failures in this sandbox (`EACCES` on `/proc/self/fd` spawn, directory fsync). The same failures occur on `master` without this change.

## Risks

- Medium-low risk. If a future Claude CLI stops the `${VAR}` expansion in `--mcp-config`, MCP calls fail authentication. They do not leak the token. The regression test pins the header shape.
- The token is now in the Claude process environment. Only the same user can read `/proc/<pid>/environ`. Other credentials are already in this environment. Shell tools that Claude starts also inherit the environment, so `env` output can still show the token. Log redaction must continue to cover bearer values.
- Tokens that already appeared in logs are not revoked by this change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and code 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
- [ ] 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

Related: #13572 removes bearer tokens from curl arguments in the agent helper scripts. This pull request covers the Claude CLI MCP configuration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)



Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1118.0-canary.828200 nightly/v2026.1119.0-nightly.0
2026-11-18 15:58:46 -06:00
DottaandClaude Opus 5.5 bb258a5429 fix(connections): explain failed app sign-ins and guide GitHub app install (#22234)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents can ask a person to connect an app, such as GitHub, through a
sign-in window
> - When that sign-in fails, the server knows the reason and records it
in the activity log
> - The sign-in window tells the opener only "failed", so the person
sees "Authorization did not complete" for every cause
> - People cannot fix the problem themselves, and support cannot help
without reading server data
> - This pull request sends the safe failure code to the opener and
shows plain copy for the common causes
> - The benefit is that a person knows what to do next, such as to
finish faster or to stay in the same session

## Linked Issues or Issue Description

**What happened?**
A user tried to connect GitHub from an agent request. The dialog showed
"GitHub couldn't connect. Authorization did not complete. Try again when
you're ready." The same text shows for every failure cause.

**Expected behavior**
The dialog should tell the user why sign-in failed and what to do next.

**Steps to reproduce**
1. Start an app connection from an agent request.
2. Let the sign-in take longer than the state lifetime, or finish it in
a different Paperclip session.
3. See the generic "Authorization did not complete" message.

**Paperclip version or commit**
`master` at 84a529df4f.

**Deployment mode**
Paperclip Cloud. The connection-intent sign-in path is the same in
self-hosted deployments.

## What Changed

- The connection-intent sign-in page now posts a `code` field with a
`failed` outcome. Only codes that match `^[a-z][a-z0-9_]{0,63}$` are
sent. Connected and declined outcomes send no code.
- Both OAuth callback catch blocks pass their failure code to that page.
- OAuth state errors now carry codes: `oauth_state_expired`,
`oauth_state_missing` and `oauth_session_mismatch`.
- The setup flow maps common codes to plain copy. Unknown codes keep the
old generic text, and raw codes never show to the user.
- The managed-connector callback now records `tool_app.oauth_failed`
with the failure code. Before, it answered 200 and recorded nothing.
- A callback whose state is already gone now answers an HTML request
with a page that posts `oauth_state_missing`. The dialog accepts it only
from its own active sign-in window.
- GitHub: before sign-in, the setup explains that Paperclip connects
through the Paperclip for GitHub app and which account to install it on.
- GitHub: when sign-in finds no usable installation, the sign-in window
passes the GitHub install and manage links (github.com only) to the
dialog. The dialog shows "Install Paperclip on GitHub" and "Manage
repositories on GitHub" next to "Try again".

## Verification

- `server`: `npx vitest run
src/routes/tool-access-connection-intent.test.ts
src/__tests__/generic-mcp-connection.test.ts` (126 passed). A new test
checks that a safe code is posted, an unsafe code is dropped, and a
connected outcome has no code.
- `server`: `npx vitest run
src/__tests__/tool-access-oauth-protocol.integration.test.ts -t "missing
sign-in state"` covers the missing-state page on both callbacks.
- `ui`: `npx vitest run src/features/connections/` (130 passed). Tests
cover the GitHub install links, which drop non-github.com links, and
missing-state messages from an old window.
- `ui`: earlier run `npx vitest run
src/features/connections/ConnectionSetupFlow.oauth.test.ts` (21 passed).
New tests check the copy for expired and cross-session sign-in, and that
unknown codes show the generic text.

## Risks

- Low risk. The postMessage adds one optional field. Old openers ignore
it.
- The state errors now include `details.code`. The status codes and
messages do not change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
code 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
- [ ] 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: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:56:16 -06:00
DottaandClaude Opus 5.5 06750cb18e fix(runner): continue a turn lost to a mid-run runnerd restore (#22235)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents in a managed sandbox run under the Paperclip runner
(`runnerd`). When `runnerd` exits mid-run, the transport relaunches it
in the same execution, and the runner restores the same conversation
> - An agent can fill the sandbox disk with its own work. `runnerd` then
cannot write its state and exits. #22068 added a disk reserve so the
relaunch succeeds. Its stated goal was that "the agent's turn can
continue and see the full disk"
> - The relaunch now works, but the turn still dies. The runner reports
the in-flight turn as `provider_turn_lost_on_restore`. The runtime sends
its single same-conversation continuation only for a session recovered
at startup under a control-plane restart claim. A relaunch inside the
live execution has neither, so the run fails as
`native_provider_terminal_failed`
> - The generic transient retry then starts on a fresh sandbox, redoes
the same install, fills the disk again, and ends in board-owned
"Recovery needed"
> - This pull request lets the execution that started a turn send the
existing one-time continuation when the runner reports that same turn
lost on restore
> - The benefit is that the agent keeps its conversation and workspace
and sees the full disk in its own tools, instead of the run dying and
retrying into the same wall

## Linked Issues or Issue Description

Refs #22068

**What happened?**
On staging, two agent tasks on the Paperclip monorepo each failed on
every attempt (5 failed runs in total). Each run used a fresh managed
Daytona sandbox with 10 GiB of disk. The agent's own `df` showed `/` at
10G of 10G with 236K free. `node_modules` used 3.2G and
`.paperclip-runtime` used 6.1G: about 3.0G of provider pack and a 2.8G
pnpm store under the session data directory. `runnerd` exited with
`failed to create private durable state temporary file: No space left on
device (os error 28)`. The transport relaunched it in about 20 s, and
runnerd restored its durable session. Then the runner reported
`turn.failed {code: provider_turn_lost_on_restore, recoverable: true}`,
and the run failed as `native_provider_terminal_failed`. Retries on
fresh sandboxes hit the same failure. The tasks ended in "Recovery
needed" with `provider_failure_meaning_unverified`.

**Steps to reproduce**
1. Run an ACPX or Codex agent through `paperclip_runner` in a managed
sandbox.
2. Have the agent fill the disk during a turn, or end `runnerd` in any
other way mid-turn while the server keeps running.
3. The transport relaunches `runnerd`, and the runner reports the turn
as lost on restore.
4. The run fails instead of continuing the turn.

**Expected behavior**
The execution that started the turn sends one continuation turn in the
restored conversation, exactly as it does after a server restart. The
agent continues from its recorded progress and sees the full disk in its
tools.

**Environment**
Managed Daytona sandbox (fleet snapshot, 4 CPU, 8 GiB memory, 10 GiB
disk), `paperclip_runner` native runtime with Claude through ACPX.

## What Changed

- `packages/paperclip-runner/src/native-session-runtime.ts`: the
execution records the turn id of the turn it starts.
`resumeInterruptedTurn` now accepts two owners of a turn lost on
restore:
- a session recovered at startup with the control-plane restart claim,
for the checkpointed active turn (unchanged), or
- a session this execution opened itself, for the turn this execution
started (new).
- All other guards stay: one continuation per run, the provider
allowlist, no compaction or goal runs, no pending runtime requests, and
the snapshot must show that same turn as restart-interrupted.
- `native-session-runtime.test.ts`: a new regression for an ACPX session
that loses its own turn to a mid-execution `runnerd` restore, plus a
negative case for a lost turn this execution never started.

## Verification

- Red before the fix: `npx vitest run
src/native-session-runtime.test.ts` failed `continues its own turn once
when runnerd is restored mid-execution` with
`NativeProviderTerminalFailure: Provider turn failed`, the same failure
seen on staging.
- Green after the fix: `native-session-runtime.test.ts` and
`native-session-runtime.provider-turn.test.ts` pass (337/337). The
existing `requires the control plane restart claim` case still refuses a
recovered session without the claim.
- `pnpm verify` (affected selection): see the CI results on this PR.
- Live acceptance: after deploy, retry the affected staging tasks and
confirm that a mid-turn `runnerd` restore leads to one continuation turn
in the same sandbox instead of `native_provider_terminal_failed`.

## Risks

- **Second executor.** The continuation can start only from the
execution that opened the session and started the turn. It is not used
for a recovered or adopted session without a claim. It runs at most once
per run (`restartContinuationStarted`). The runner emits this code only
after it proves the old provider process ended.
- **Run starts.** This starts no new runs. It adds at most one turn to a
run that would otherwise fail and schedule a fresh-sandbox retry. During
a crash loop, `MAX_UNSTABLE_RUNNER_RESTORES` in the transport still
fails the transport.
- **Disk still full.** If the continuation fills the disk again, the
second lost turn finds `restartContinuationStarted` set, and the run
fails as it did before. The worst case is the current behavior.
- **Not in this PR.** Paperclip's own footprint (about 3G of provider
pack per sandbox, and a per-session pnpm store) and classifying a
disk-full failure so it does not retry into the same wall. Both are
follow-ups.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, browser, and a code-tracing subagent).

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:55:16 -06:00
DottaandClaude Opus 5.5 4b189690b4 docs(plans): stage production settings for the team's next deploy (#22224)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip Cloud now sends analytics directly to PostHog, and this is
live on staging
> - The plan doc records the rollout state and the steps that remain
> - Production needs an ordered, reversible rollout with clear decisions
> - This pull request records how production settings are staged for the
team's next deploy
> - The benefit is one reviewed place that says what is done, what is
next, and how to roll back

## Linked Issues or Issue Description

**What is the problem?**
Production app deploys are coordinated by the team, and the plan needs a
way to prepare the settings without restarting user stacks.

**What do you propose?**
Record the revised production approach: stage settings now without
restarting user stacks, and let the team's next production deploy turn
them on. Add a note for that deploy with what turns on, canary checks
and rollbacks.

**Why does it matter?**
Production changes must be ordered and reversible, and the open
decisions must be visible.

## What Changed

- Add "Revised plan" and "Note for the team's production deploy" to
Phase 5 of `doc/plans/2026-11-17-cloud-direct-posthog.md`.
- No code changes.

## Verification

- Documentation only.

## Risks

- Low risk. Documentation only.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with 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
- [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: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:43:46 -06:00
DottaandClaude Opus 5.5 46e38e1387 fix(native): let the outgoing server checkpoint its idle warm session while its follow-up has not started (#21887)
**HOLD: do not merge until the coordinator confirms (merging resets the
zero-downtime gates).**

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A deploy swaps servers with an overlap. A warm agent session stays
with the outgoing server that ran its last turn.
> - When that turn finishes during the overlap, the outgoing server
saves its idle session and closes it. A checkpoint fence decides whether
the save is still allowed.
> - The task's follow-up run usually starts on the incoming server at
the same moment. It waits for the outgoing owner (#21774), and #21791
lets the outgoing server save while the follow-up is parked on it.
> - The fence still refused the save
(`native_runner_checkpoint_owner_lost`) in every other state of the same
unstarted follow-up. In release-swap waves the close then fails at least
once and retries, and the follow-up waits longer. If every attempt hits
such a window, the owner stays until the outgoing server stops, up to
the 510 s overlap. Speed is a requirement.
> - This pull request makes the fence accept the outgoing server's final
save in every state in which the follow-up has not started: no process,
no own process start, no own checkpoint, `attempt = 0`, same session. It
still refuses when the follow-up names another owner or has started.
> - The benefit is that the outgoing server closes its session on the
first attempt, and the follow-up continues at its next owner check.

## Linked Issues or Issue Description

Refs #21791, #21774, #21782

**What happened?**

Release-swap waves logged `idle warm native session close failed …
native_runner_checkpoint_owner_lost`. The close worked on a later
attempt. Two recent waves, traced with the wave's 2-second run samples:

| Wave | Outgoing run | Attempt | Follow-up at that moment | Old fence |
| --- | --- | --- | --- | --- |
| 13:48Z | `480c86e4` (finished 14:29:04.7) | 1, 14:29:07.7 |
`5396e5ab`, started 14:29:05.6 on the incoming server: `preparing`
(legacy, incoming boot) at 06.2, native `observed` with no owner at 08.2
| refused: a preparing follow-up was accepted only on the outgoing
server's own boot, and a native follow-up only when parked or re-claimed
with `waitingForOwner` |
| 15:58Z | `87de6f54` (finished 16:16:14.1) | 1, 16:16:19 | `2009f6bb`,
started 16:16:18.7: `preparing` (legacy, incoming boot) at 19.8 |
refused: foreign preparation |
| 15:58Z | `87de6f54` | 2, 16:16:27 | `2009f6bb`: native `observed`, no
owner from 21.8 to 25.8, owner stamped at 27.8 | refused: selected
follow-up before its first owner check, or a park or re-claim without
`waitingForOwner` |

In each case the follow-up was the task's current run and had no
process, no process-start event and no checkpoint rows. No successor
claim or stale epoch held the session: the outgoing server's own run had
committed and released its lease. The fence refused only because it did
not recognize these states of the same unstarted follow-up.

**Expected behavior**

The outgoing server saves and closes the session on the first attempt
while the follow-up is in any unstarted state. The follow-up then sees
the saved session at its owner check and continues without parking (or
within one recheck if it already parked).

**Steps to reproduce**

1. Run a warm native session on a remote sandbox, and let a run finish
on server A during a swap to server B.
2. Let B claim the follow-up right away.
3. While B prepares it, selects native execution, parks it, or re-claims
it, A saves and closes its idle session. The fence refuses the save.

**Paperclip version or commit**

master `f61b919701` (merged in). The waves ran on master builds without
this pull request.

## What Changed

- `native-runner-checkpoint.ts`: the parked-follow-up check is now
`unstartedSuccessorOfOwner`. It takes `FOR SHARE` on the follow-up's
finalization row (if any), then on its run row, in that order, inside a
savepoint. The claim and defer paths use the same order. If native
selection created the finalization row while the fence waited for the
run lock, the fence rolls the savepoint back, which releases the run
lock, and takes both locks again in the same order (at most twice). A
last statement then reads the current state again and accepts one of
these states:
- **Preparing on any server** (new): the run is still `legacy`,
`preparing`, on this task, has a live controller lease and no process,
and has no finalization row. Before, only the outgoing server's own boot
was accepted.
- **Selected, before its first owner check** (new): native, finalization
`observed`, `attempt = 0`, no lease, no failure, empty recovery history.
  - **Parked**: as before, but `waitingForOwner` may be absent.
- **Re-claimed**: as before (live `same_run_resume` claim by the current
controller), but `waitingForOwner` may be absent, as in claims from a
previous release.
- These conditions apply to every state and are unchanged: running; no
own process-start event; no own checkpoint rows. For the native states,
also: same company, task and native session; `attempt = 0`; no result;
no process, unless it is the identity inherited from the outgoing run
(`inheritedProcessIdentityRunId`). The fence still requires an accepted
result and no new work.
- A `waitingForOwner` that names another run or boot is still refused.
- `SAME_RUN_RESUME_DISPOSITION` moves to the leaf module
`same-run-resume-disposition.ts`. The fence no longer imports
`scheduled-resume-continuation.ts`, so the runner E2E server does not
load the executor and `@paperclipai/plugin-sdk` through it
(`server-startup-import-graph.test.ts`).
- The run-row share lock makes native selection (`runtime_selection`
locks the run `FOR UPDATE`) and process start wait for the save to
commit. A save that waited reads the committed state in its last
statement and is refused if the follow-up has started.
- Tests, real Postgres:
  - `native-controller-recovery.integration.test.ts`, new:
- The outgoing server saves and closes while the incoming server
prepares the follow-up.
    - Native selection of that follow-up waits for the save.
- A save that waited while native selection held the run lock and
created the coordinator is accepted (Greptile review).
- It saves and closes while the follow-up is selected but before its
owner check, also with an inherited process identity, and the
follow-up's check resolves at once.
- It saves and closes while the follow-up is parked or re-claimed
without `waitingForOwner`, including a claim entry in the previous
release's shape.
- Still refused, preparing: expired controller lease, `dispatching`, own
process, own process-start event, other task.
- Still refused, selected: own process, a process inherited from another
run, own process-start event, own checkpoint, other session, admitted
(`attempt = 1` with a lease).
    - The outgoing-server fixtures share one helper.
- `native-harness-backup-storage.integration.test.ts`: the harness
backup fence shares this check. A released owner whose follow-up is
still preparing on another server now replaces its selected backup.
`expired_preparation`, `dispatching_successor` and `foreign_native`
still keep the old backup.
- `native-runner-restart-recovery.integration.test.ts`: the
`foreign_preparation` early-retirement case now expects the save to
succeed. `expired_preparation`, `dispatching_successor`, `wrong_issue`,
`unclaimed_successor` (another session) and `foreign_native_preparation`
still expect a refusal.
- From the earlier commits of this pull request: the re-claimed state,
`sameRunResumeClaimEntry` recording `waitingForOwner`, the run-row lock
and the post-lock recheck.

## Verification

- Red/green for this round (only the fence source changed between runs):
- With the fence at `ed7227eeda` (this pull request before this round),
9 tests fail with `native_runner_checkpoint_owner_lost`: preparing close
(+ `foreign_preparation` ×2), native-selection ordering,
selected-before-check ×2, waiting-without-owner ×3. The 11 new refusal
cases pass both before and after.
- With the fence change:
`native-controller-recovery.integration.test.ts` and
`native-runner-restart-recovery.integration.test.ts` 306 passed, 14
skipped. `native-harness-backup-storage.integration.test.ts` 73 passed.
`scheduled-resume-continuation.test.ts`,
`native-runner-checkpoint-save.test.ts` and
`native-controller-recovery.integration.test.ts` 110 passed.
- Savepoint restart: the new waited-on-native-selection test fails with
`native_runner_checkpoint_owner_lost` without it, and passes with it.
- `tests/runner-e2e/server-startup-import-graph.test.ts` failed in CI at
`cc513d9434` (import path through `scheduled-resume-continuation.ts`).
It passes locally after the move.
- Earlier rounds (unchanged): red on master for the re-claimed close,
the process-start ordering and the claim ordering; red without the
run-row lock; red without the recheck.
- `tsc --noEmit` for `server` passes.
- `pnpm verify` (base `f61b919701`) selected 2842 of 3683 files, because
the checkpoint module has a wide import graph. The reusable job passed:
2 files, 12 tests. The fresh job was cut off locally (exit 144, no test
failure printed). Required CI supplies that coverage.
- `node scripts/agent-preflight.mjs` stops at `pnpm install
--frozen-lockfile`: on master, `server/package.json` lists
`posthog-node` (#22006) and the lockfile does not have it yet. CI
resolves the lockfile inline. Locally, dependencies were installed
without the frozen lockfile, and `pnpm-lock.yaml` was not committed.
- Not run: a release-swap wave. The coordinator runs the gates.

## Risks

- The fence is wider. It now accepts the outgoing server's final save
while the follow-up is in any state before it starts. The save needs an
accepted result and no new work. The follow-up must have no process
(except the identity inherited from this run), no process-start event,
no checkpoint of its own, and `attempt = 0`. A follow-up that names
another owner, holds an expired claim, has been admitted, or is in
another session is still refused.
- A follow-up that another server is preparing is now accepted. It has
not touched the session: it runs the owner check after native selection,
and native selection waits for the save to commit. The earlier
same-boot-only rule was stricter than needed.
- The fence takes share locks on the follow-up's rows whenever it
reaches this check, also when it then refuses. The save transaction is
short. The lock order is the finalization row, then the run row, as in
the claim and defer paths.
- Previous-release state: a claim or park written by a release without
`waitingForOwner` is now accepted, not refused. No stored shape changes.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code
execution in Claude Code.

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:37:16 -06:00
DottaandClaude Opus 5.5 397f163c7f fix(issues): show tasks held by a resolved no-replay hold as Blocked (#22215)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Agents can schedule a follow-up check (a monitor) on a task. The task then shows as "Monitoring" until the check is due.
> - A failed run can leave a recovery record that blocks replay of its work. The record can have the status `resolved` and still block, because its evidence keeps `automaticRecovery.replay = "blocked"`.
> - Wake admission treats that record as a hold. It refuses every wake for the task, including the due monitor check, and records the skip with `execution_reconciliation_required`.
> - The task display status counts only `active` and `escalated` recovery records. Thus the task shows "Monitoring" with an overdue check, not "Blocked". The board does not see that a person must act. Agents re-arm the check, and the check stays overdue for days.
> - This pull request makes the display status show these held tasks as "Blocked". It uses the part of the wake-admission hold predicate that is always effective and cheap to query.
> - The benefit is that a task whose wakes are held shows as "Blocked" in the list, in search, in counts and in summaries, and the person who must act can find it.

## Linked Issues or Issue Description

(B) No issue exists. Bug report:

**What happened?**
Scheduled follow-up checks on agent tasks stayed overdue for many days. Each due check was skipped with the reason `execution_reconciliation_required`. One skip record had more than 25,000 merged attempts. The tasks did not show as "Blocked". They showed as "Monitoring" (or as in progress) with an overdue check. Agents re-armed the check, but the check never started.

**What did you expect to happen?**
When wake admission holds a task, the task shows as "Blocked", so a person can see it and use the recovery controls.

**Steps to reproduce**
1. Give an agent an `in_progress` task with a monitor.
2. Add a recovery record for the task with status `resolved`, a reconciliation cause (for example `provider_failure_meaning_unverified`) and evidence `automaticRecovery.replay = "blocked"`.
3. Read the task. `getExecutionBlocker` returns the hold and wake admission refuses the monitor wake.
4. See that `displayStatus` is `monitoring`, not `blocked`.

**Paperclip version or commit**
`master` at 8282d386da.

Related open PRs: #14590 and #14156 change how no-replay holds are released. This PR does not change hold release. It only makes the held task visible.

## What Changed

- `server/src/services/issue-display-status.ts`: An agent task with lifecycle status `in_progress` now shows `blocked` when it has a recovery record with these properties:
  - The cause is a reconciliation cause other than `legacy_execution_requires_reconciliation`.
  - The evidence has `automaticRecovery.replay = "blocked"`.
  - The evidence does not have the legacy workspace-restore schema.
  - The task is not a conversation.
- For these records, `executionBlockerPredicate` is always true and `restoreHoldReleasedForCurrentOwnerPredicate` is always false. Thus "Blocked" never shows for a task that wake admission would wake. The exceptions of the full predicate apply only to legacy holds, legacy workspace-restore holds and conversation boundaries. Those keep their current display.
- The full admission predicate is not used in the projection. I tried it first, and list queries became 3 to 4 times slower, because every list, search and count query includes this projection.
- `server/src/__tests__/issue-display-status.test.ts`: New regression test. It also checks that `getExecutionBlocker` agrees with the display status before and after the hold allows replay.

## Verification

- Failing before the fix: `pnpm --dir server exec vitest run src/__tests__/issue-display-status.test.ts`. The new test "shows an overdue monitor behind a resolved no-replay execution hold as Blocked, not Monitoring" failed with `AssertionError: expected 'monitoring' to be 'blocked'`.
- Passing after the fix: the same command. 21 of 21 tests pass.
- Affected suites: `vitest run` on `issue-display-status`, `issue-summaries-routes`, `blocked-inbox-review-wait-scope`, `company-search-service`, `issues-service`, `issue-list-assignee-filter-routes`, `status-cards` and `heartbeat-issue-liveness-escalation`. 8 files, 361 tests pass.
- List cost: a local probe (40 `issueService.list` calls) measured about the same time per call as `master`.
- Typecheck: `pnpm --dir server typecheck` (all layers) passes.
- Not run locally: the full `pnpm verify` selection (2,923 files). CI runs it.

## Risks

- Behavior change: more agent tasks can show as "Blocked". This occurs only when wake admission already refuses their wakes. The task lifecycle status, locks and recovery records do not change. This change does not write data.
- Query cost: the display status adds one small `EXISTS` subquery on `issue_recovery_actions` by company and source task. It runs only for agent tasks that are `in_progress` with no queued or running run and no active recovery record.
- Coverage: tasks held by a resolved legacy reconciliation hold, or by a legacy workspace-restore hold, still show their current status. Their release rules need run-level checks that are too costly for this projection.
- `in_review` and other lifecycle statuses keep their current display.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use (shell, file edit, test runs).

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)



Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:27:05 -06:00
DottaandClaude Opus 5.5 35563b7de5 fix(railway): report restricted environments instead of a consent error (#22214)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - The Railway connection gives agents governed deployment tools, such as `list-deployments`
> - Railway Environment RBAC lets non-admin members see a restricted environment, but Railway denies reads of its services, deployments, and logs
> - The client maps this denial to `railway_api_authorization_required` and tells the user to reconnect or to use IDs from a consented workspace
> - That advice is wrong for this case: workspace consent is correct, and reconnecting does not change the result
> - This pull request identifies the restricted environment and reports the correct remedy
> - The benefit is that agents and operators get a clear, actionable error instead of an incorrect reconnect loop

## Linked Issues or Issue Description

(B) No public issue exists. Bug description:

**What happened?**
An agent called `paperclip-railway-list-deployments` for a service. In the same session, `list-projects`, `list-services`, and `list-environments` succeeded for the same project. The deployment-history call failed every time with `railway_api_authorization_required` and the message "Use IDs from a workspace selected during consent, or reconnect". The project-level reads prove that workspace consent is correct. The denied environment is restricted for the connected member, so the message sends the user to the wrong fix.

**Expected behavior**
When Railway denies the environment-scoped target check because the environment is restricted, the tool must report a distinct error. The error must say that a Railway project admin must grant access. It must not tell the user to reconnect.

**Steps to reproduce**
1. Connect Railway with a member (non-admin) account in a workspace that has a restricted environment.
2. Call `paperclip-railway-list-environments` for the project. The restricted environment is in the list.
3. Call `paperclip-railway-list-deployments` (or `service-status`) for a service in that environment.
4. Railway returns `Not Authorized`, and Paperclip reports a workspace consent error.

**Paperclip version or commit**
`master` at 8282d386da.

## What Changed

- `server/src/services/railway.ts`: When the target query fails with an authorization denial, the client reads the project's environments with `canAccess`. If the requested environment has `canAccess: false`, the client throws `railway_environment_restricted` (HTTP 403) with the admin-access remedy. In all other cases, the client throws the original error. If the access check fails, the client also throws the original error. The access check is a read query. No mutation runs after a denied target check.
- `server/src/services/railway.ts`: `list-environments` now returns `canAccess` for each environment, so agents can choose an accessible environment before they call a target tool.
- `server/src/__tests__/railway.test.ts`: Adds a regression test for the restricted, accessible, and unknown cases.
- `doc/connections/RAILWAY.md`: Adds a recovery entry for the new error code.

## Verification

- Failing before the fix: `cd server && npx vitest run src/__tests__/railway.test.ts`. The new test "reports a restricted environment instead of a workspace consent error when Railway denies the target" failed. It expected `code: "railway_environment_restricted"`, but it received `code: "railway_api_authorization_required"`. The other 28 tests passed.
- Passing after the fix: the same file passes (29/29).
- Related suites pass: `npx vitest run src/__tests__/railway.test.ts src/__tests__/railway-connection.test.ts src/__tests__/railway-ssh.test.ts src/__tests__/connector-tool-policy.test.ts` (4 files, 63 tests).
- Scoped `tsc --noEmit` with the server `tsconfig.json` for the changed files passes.
- Not run: the full server typecheck and `pnpm verify`. In the test sandbox, they used more than the 8 GB memory limit. CI must confirm them.
- Public reference for the provider behavior: https://docs.railway.com/enterprise/environment-rbac

## Risks

- Low risk. The change applies only after Railway has already denied the target check. It adds one read query in that case.
- If Railway removes or renames `canAccess`, the access check fails, and the client throws the original error, as before this change.
- The access check reads the first 100 environments of the project. If a project has more environments, the client throws the original error.
- `list-environments` output gets one more field.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), agentic coding with tool use (shell, file edits, test 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
- [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

🤖 Generated with [Claude Code](https://claude.com/claude-code)



Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:26:56 -06:00
DottaandClaude Opus 5.5 01d74a52a2 fix(connections): name an expired sign-in in connection search (#22211)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Agents use connection search to find out if they can use an app, and what a person must do when they cannot
> - When an OAuth provider rejects a refresh token, Paperclip disables the shared connection and records `oauth_reauthorization_required`
> - Connection search then gave only the generic reason "Connection needs attention"
> - Agents could not tell a person the exact action. They had to read large app attention payloads to find the cause
> - This pull request makes connection search name the connection whose sign-in expired and say that a person must reconnect it
> - The benefit is a clear blocker that agents can report in one step, so the connection owner can renew the sign-in sooner

## Linked Issues or Issue Description

**What happened?**
A shared OAuth connection (for example, Sentry) came to the end of its provider grant. Paperclip tried the refresh token. The provider rejected it. Paperclip correctly disabled the connection and set its error to `oauth_reauthorization_required`. After that, `connections_search` returned `state: "needs_user_action"` with the reason "Connection needs attention". Scheduled agent work that needed the app stopped. The agents could not name the cause or the human action from the search result.

**Expected behavior**
Connection search tells the agent that the sign-in for the named connection expired, and that a person who manages the connection must reconnect it.

**Steps to reproduce**
1. Make a shared OAuth tool connection and give an agent access to its tools.
2. Make the provider reject the refresh token (for example, `invalid_grant`). Paperclip sets the connection to draft, disabled, health `error`, and last error `oauth_reauthorization_required`.
3. As the agent, search connections for the app.
4. See the reason "Connection needs attention". It does not say that the sign-in expired.

## What Changed

- `server/src/services/connection-intents.ts`: connection search reads the grants of each matching connection. When a grant in the caller's audience (the organization, the responsible user, or the agent) has status `needs_reauthorization`, and no grant in that audience is active, the reason names that connection. The reason says that the connection must be signed in again, and that a person who manages it must reconnect it on its app page.
- The search uses the same audience rule that protects indexed tool descriptions. A grant of another person does not show the name of that connection.
- The state, `connectionId`, and all access checks do not change.
- `server/src/__tests__/connection-intents-service.test.ts`: add two regression tests. The first test confirms that the healthy connection is `ready`. Then it writes the rows that a rejected refresh writes for an organization grant (grant `needs_reauthorization`, connection `draft` and disabled, no `lastError`), and examines the reason. The second test makes sure that the private connection of another person is not named.

## Verification

- Failing before the fix (in `server/`): `pnpm exec vitest run src/__tests__/connection-intents-service.test.ts -t "must be renewed"`. The shared test failed with `AssertionError: expected 'Review identity and access for this agent' to contain 'Saved sentry'`.
- The private-connection test failed against the first commit of this PR (`lastError` match without an audience check) with `expected 'The sign-in for "Private Sentry of another person" expired. ...' not to contain 'Private Sentry of another person'`.
- Passing after the fix: `connection-intents-service.test.ts` passes (37 of 37).
- Related suites pass: `agent-setup-connection-intents`, `connection-aggregator-fallback`, `satisfied-connection-intents` (168 of 168 with the file above).
- `pnpm run typecheck` in `server/` passes.
- The grant state comes from the refresh writer in `grant-refresh.ts`. Existing tests in `tool-access-service.test.ts` make sure that a rejected refresh sets the grant to `needs_reauthorization`.
- I did not run the full `pnpm verify`.

## Risks

- Low risk. The change only changes the text of one search reason. It does not change state, access decisions, or what agents can call.
- The reason does not use `lastError`, because health checks write display text into that column, and the default refresh path does not write it.
- The member-removal path also sets remaining grants to `needs_reauthorization`. The text "must be signed in again" is correct for that case too.
- I examined the refresh path. Paperclip already tries the refresh token before it marks the grant. This PR does not change that path.
- Out of scope: Paperclip does not send a notification to the connection owner, and the connection request card does not offer to reconnect the existing connection. These need separate changes.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution in an agent harness.

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)




Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:25:00 -06:00
DottaandClaude Opus 5.5 c36e791bd9 fix(native): back off and retry a provider rate limit that reports no reset (#22216)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Native runs drive ACP agents, such as Claude, through the runner. The runner types each provider failure for the server.
> - When a provider limit stops a turn, the server holds the task. It retries the task automatically at the reset that the provider reports (#20692).
> - Claude can reject a request at the account rate limit with "This request would exceed your account's rate limit. Please try again later." This text has no reset time and no window.
> - The server then plans no automatic Retry. The task stays blocked until a person retries it, and the case work stops before a final reply.
> - This pull request gives a `rate_limit` failure without a reported reset the default provider-limit cooldown, and then requests the task's Retry.
> - The benefit is that a short account rate limit no longer strands a task. The existing Retry admission keeps the saved work and all gates.

## Linked Issues or Issue Description

Refs #20692, #19246, #21100

**What happened?**

A native task ran on a Claude agent. In the middle of the turn, Claude returned HTTP 429 with "This request would exceed your account's rate limit. Please try again later." The runner typed the failure as `rate_limit`, with no `retryAt`. The server put the task on hold with "Restore model provider usage capacity, then retry the task. The provider did not report when its usage limit resets." It did not plan an automatic Retry. The task stayed blocked until a person retried it.

**Expected behavior**

A rate limit passes by itself. Paperclip should wait a bounded time, and then retry the task. It should keep the saved work and should not start another request before the wait ends.

**Steps to reproduce**

1. Run a native task on a Claude agent whose account is at its rate limit.
2. Let Claude reject a request in the turn with the 429 account rate-limit text above.
3. See that the task hold has no reset time and that no automatic Retry is planned.

**Paperclip version or commit**

`master` at 8282d386da.

## What Changed

- `readNativeUsageLimitReset` (server, native runtime) now gives a `rate_limit` turn failure without a reported reset an estimated reset. The estimated reset is the failure time plus `PROVIDER_LIMIT_DEFAULT_COOLDOWN_MS` (one hour). This is the same wait that already holds the agent's new work after the same failure, so both holds end at about the same time.
- The reset carries an `estimated` flag. The hold text says that the provider did not report the reset, and it gives the time when Paperclip will retry.
- A `quota_exhausted` failure without a reported reset does not change. It still waits for a person, because an exhausted allowance does not pass by itself.
- The existing bounds still apply: a maximum of three automatic Retries in a row without a successful run, Retry admission gates, and the accountable-user check.
- This change is a fallback. When the runner sets `retryAt` (for example, #21100 for a named rate-limit window) or the text contains a reset, Paperclip uses that time.

## Verification

- New test in `server/src/services/native-runtime/native-provider-capacity.integration.test.ts`: "backs off and retries a Claude account rate limit that reports no reset".
- Before the fix, the test failed: `AssertionError: expected NaN to be greater than or equal to 1795028502736`. The hold had no `providerLimitResetAt`, because no reset was planned.
- After the fix: `cd server && pnpm vitest run src/services/native-runtime/native-provider-capacity.integration.test.ts` passes (11 tests).
- Related files pass: `native-provider-limit-cooldown.integration.test.ts`, `src/__tests__/heartbeat-provider-limit-wait.test.ts`, `task-interruption-presentation.test.ts`, and the capacity file (4 files, 90 tests).
- `cd server && pnpm typecheck` passes.
- `pnpm verify` selected 2,925 of 3,792 Vitest files, because the changed module is deep in the server import graph. Its first selected group passed (2 files, 12 tests). I stopped the broad local run and rely on the required CI test checks for that coverage.

## Risks

- Low risk. The change applies only to a native turn failure that is typed `rate_limit` and has no reported reset.
- If the account stays at its limit for more than one hour, the automatic Retry can fail again. After three automatic Retries in a row, the task waits for a person, as before.
- The task stays in the blocked state during the wait, as it does for a reported reset. A person can select Retry to start it sooner.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and code 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 (no doc change is necessary: no subsystem doc describes this hold, and the hold text and tests describe the behavior)
- [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: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:24:52 -06:00
DottaandClaude Opus 5.5 f472991647 fix(native-runtime): resolve assigned tool names to the authorized alias (#22213)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work.
> - Native runners give agents their assigned app tools through two wrapper tools: `paperclip_search_assigned_tools` and `paperclip_call_assigned_tool`.
> - Search returns each tool with a hashed alias (`app_<readable>_<digest>`). The description also shows the display name.
> - Agents sometimes pass the gateway tool name or the display name instead of the alias, in `schemaTool` or in the call `name`.
> - The wrapper rejected these values with a bare `assigned_mcp_tool_unknown`. The agent had to search the catalog again before it could call the tool.
> - This pull request resolves an unambiguous name to the authorized alias, and gives a corrective error when the name is not known.
> - The benefit is fewer failed tool calls and fewer repeated catalog searches, with no change to authorization.

## Linked Issues or Issue Description

**What happened?**
An agent searched its assigned tools and then called a tool with the gateway name or the display name (for example `sql_query`). The search with `schemaTool` and the call both failed with `assigned_mcp_tool_unknown`. The call error did not tell the agent what to do.

**Expected behavior**
When the name identifies exactly one tool in the session catalog, the wrapper uses that tool. When the name is not known or is ambiguous, the error tells the agent to use the exact name from search.

**Paperclip version or commit**
`master` at 8282d386da.

**Steps to reproduce**
1. Assign an app tool with the display name `sql_query` to an agent on an on-demand native runner.
2. Call `paperclip_search_assigned_tools` with `{"query":"","schemaTool":"sql_query"}`.
3. Call `paperclip_call_assigned_tool` with `{"name":"sql_query","arguments":{...}}`.
4. See `assigned_mcp_tool_unknown` for both calls.

## What Changed

- `server/src/services/native-runtime/assigned-mcp-tools.ts`: add `resolveAssignedName`. It accepts the exact alias. If the value is not an alias, it looks for tools whose gateway name or display name is equal to the value. It resolves only when exactly one tool in the session's pinned catalog matches in either field. It trims surrounding white space.
- Search with `schemaTool` uses the resolved alias. The fresh-grant and work-mode filters still apply to the result.
- `paperclip_call_assigned_tool` uses the resolved alias. An unknown name returns `assigned_mcp_tool_unknown: name must be an exact name returned by paperclip_search_assigned_tools. Search assigned tools again and use the returned name.`
- A name that matches more than one tool returns a different error: `assigned_mcp_tool_unknown: name matches more than one assigned tool. Use the exact name returned by paperclip_search_assigned_tools.` The `schemaTool` path gives the same error, with the text `schemaTool` and `inputSchemaRef`.
- `server/src/services/native-runtime/assigned-mcp-tools.test.ts`: add regression tests.

## Verification

- Failing before the first fix: `pnpm --filter @paperclipai/server exec vitest run src/services/native-runtime/assigned-mcp-tools.test.ts -t "resolves a gateway name"` failed with `promise rejected "Error: assigned_mcp_tool_unknown: schemaTool must match an authorized inputSchemaRef..." instead of resolving`.
- Failing before the review fix (second commit):
  - `rejects a name that is one tool's gateway name and another tool's display name` failed with `promise resolved "{ content: [...] }" instead of rejecting`. The old code ran the read tool `sql_query`, but the write tool has the display name `sql_query`.
  - `resolves a gateway name or unique display name ...` failed with `expected ... 'assigned_mcp_tool_unknown: name matches more than one assigned tool' but got 'assigned_mcp_tool_unknown: name must be an exact name ...'`.
- Passing after the fix: the full file `src/services/native-runtime/assigned-mcp-tools.test.ts` passes (59 of 59 tests).
- The tests also check these safety conditions:
  - An ambiguous display name (two tools named `search`) is rejected, on search and on call.
  - A name that is the gateway name of one tool and the display name of a different tool is rejected, and the gateway receives no call.
  - A write tool that the display name resolves to is still denied in planning mode.
  - A revoked tool is still rejected after the fresh grant list changes.
  - A tool that is not in the pinned catalog is still rejected.
  - The gateway receives only the resolved gateway tool name.
- No other code or test depends on the changed error text (`git grep assigned_mcp_tool_unknown`).
- Not run locally: the full server `tsc --noEmit`. The sandbox did not have enough memory and disk for it. CI runs the typecheck. It passed on the first commit.
- CI on the first commit: `Verify Paperclip Runner (vitest native server)` did not fail a test. All tests that ran passed. The job stopped because the CI runner received a shutdown signal. The cancelled jobs stopped for the same reason.

## Risks

- Low risk. Resolution only maps to tools that are already in the session catalog. The same permission, work-mode, fresh-grant, and gateway checks apply after resolution.
- A name that matches more than one tool, in either field, is not resolved. The agent must use the alias.
- Direct (non-wrapper) tool calls still require the exact alias.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution in an agent harness.

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)





Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:24:45 -06:00
DottaandClaude Opus 5.5 37de2b7259 fix(tools): keep audit summaries valid jsonb when the cut lands inside an emoji (#22207)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Agents call connector tools through the tool gateway. The gateway writes an audit row in `tool_call_events` for each call.
> - The audit row keeps short request and result summaries in `jsonb` columns. `summarizeToolValue` cuts long summaries to 3997 UTF-16 code units.
> - When the cut falls between the two halves of an emoji, the summary ends in a lone high surrogate. PostgreSQL `jsonb` rejects this value.
> - The audit insert then fails. The agent gets the database error and not the connector result.
> - This pull request makes the cut keep whole characters.
> - The benefit is that connector calls with long, emoji-rich results return their result and keep their audit record.

## Linked Issues or Issue Description

**What happened?**
Some connector tool calls failed with a database error. The error text starts with `Failed query: insert into "tool_call_events"`. The connector call itself worked, but the agent did not get the result. This occurred in a small part of calls (less than 1%).

**Expected behavior**
The connector call returns its result. Paperclip writes the audit row for the call.

**Steps to reproduce**
1. Call a connector tool that returns a long result (more than 4000 characters) with emoji in it.
2. Make sure an emoji is at the summary cut point (UTF-16 code unit 3997 of the serialized value).
3. The `tool_call_events` insert fails with `22P02 invalid input syntax for type json` ("Unicode low surrogate must follow a high surrogate"). The tool call returns that error.

**Relevant logs or output**
`Failed query: insert into "tool_call_events" (...)` from the gateway `call_completed` audit write. The row has request and result summaries.

## What Changed

- `server/src/services/tool-content-guards.ts`: `summarizeToolValue` now cuts long summaries with a small `cutWholeCharacters` helper. If the last kept code unit is a high surrogate, the helper drops it. The summary is still at most 4000 code units. The `sha256` and `sizeBytes` values do not change, because they use the full serialized value.
- `server/src/__tests__/tool-content-guards.test.ts`: add a regression test. It puts an emoji across the cut point and checks that the summary has no lone surrogate.

## Verification

- Failing before the fix: `pnpm --dir server exec vitest run src/__tests__/tool-content-guards.test.ts -t "without splitting an emoji"` failed. The received summary ended with a lone high surrogate before `...`, and the expected summary did not.
- Passing after the fix: the same command passes. The full file passes (47 tests).
- Database check: on embedded PostgreSQL, the old summary shape as `jsonb` fails with `22P02` ("Unicode low surrogate must follow a high surrogate"). The new summary shape is accepted. I used a temporary probe for this check. I did not commit it.
- `pnpm --dir server typecheck`: no errors in `server`. The local run showed errors only in `cli` and `kv-demo-mcp-server`, because I installed only the server dependencies (low disk space).
- Not run: the full `pnpm verify`. `prompt-injection-prevention.test.ts` does not load in my environment (`baseURL must be a non-empty string`). The same error occurs on unchanged `master`.

## Risks

- Low risk. The change affects only the readable summary text. A summary can be one code unit shorter when the cut point is inside an emoji. Hashes, sizes, redaction, screening, and authorization do not change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution, in Claude Code.

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)



Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:24:18 -06:00
DottaandClaude Opus 5.5 57e85d0d10 fix(adapter-utils): wait for a replacement GitHub broker after a controller restart (#22209)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for work
> - Agents in sandbox tasks use managed `git` and `gh` launchers. Each launcher gets a GitHub credential from a broker for each command.
> - A controller restart stops the broker of a task. The provider in the sandbox continues to run. The restored controller then writes a replacement broker location to `broker.json`.
> - The launcher read `broker.json` one time only. It retried a transport failure for about 1.5 seconds. Then it ran the command without credentials.
> - Thus, commands in the restart window failed with "You are not logged into any GitHub hosts" or "could not read Username". Agents lost pull-request checks and pushes, but the GitHub connection was healthy.
> - This pull request makes broker-file launchers wait for a bounded time and read `broker.json` again before each retry.
> - The benefit is that GitHub commands continue with managed credentials through a controller restart.

## Linked Issues or Issue Description

No public issue exists. This is the bug description.

**What happened?**

A sandbox task ran `gh` or `git` while the controller restarted. The launcher wrote `Paperclip: GitHub broker_transport_unavailable; continuing without managed credentials.` Then `gh` wrote "You are not logged into any GitHub hosts", and `git` wrote "could not read Username". Private reads, pushes and pull-request commands failed. Failures occurred in many tasks at the same time, for some minutes.

**Expected behavior**

The launcher waits for the replacement broker for a bounded time. Then it uses the managed credential. If the broker does not return, the launcher continues without credentials and shows the same diagnostic as before.

**Steps to reproduce**

1. Write a broker-file launcher. Set `broker.json` to a closed local port.
2. Run `gh` through the launcher.
3. After 3 seconds, write a reachable broker location to `broker.json`.
4. The command ran without credentials before the replacement was written.

**Relevant logs or output**

`Paperclip: GitHub broker_transport_unavailable; continuing without managed credentials.` followed by `You are not logged into any GitHub hosts. To log in, run: gh auth login`.

## What Changed

- `packages/adapter-utils/src/github-launcher.ts`: Broker-file launchers retry for up to 60 seconds. Before each retry, they read `broker.json` again. A replacement broker is used when the restored controller publishes it.
- The launcher retries two failure types in this wait: a refused or failed connection, and an HTTP 503 answer. With HTTP/2, the sandbox gateway can continue to listen after its controller connection closes. It then answers `503 {"error":"bridge_unavailable"}`.
- HTTP 401 and 403 answers are real denials. The launcher does not wait for them.
- If `broker.json` cannot be read or parsed (for example during a rewrite), the launcher keeps the last broker location and continues the wait. If `broker.json` is missing, has no broker, or has an empty URL or token, the launcher stops the wait at once, because the access of the task ended. (When a replacement bridge cannot start, the controller writes empty values.)
- After the third failure, the launcher writes one line to stderr: it waits for the credential service to return.
- Launchers with an inherited broker URL keep the old short retry budget and the old 503 behavior. Their URL cannot change, so a longer wait cannot help.
- `packages/adapter-utils/src/github-launcher.test.ts`: Regression tests for three outage types (a closed port, a 503 `bridge_unavailable` gateway, and a partly written `broker.json`). Other tests remove `broker.json` or write empty values to it during the wait, and check that 401 and 403 answers do not wait.
- `doc/execution-github-identity.md`: One sentence describes the wait.

## Verification

- Failing before the first fix: `waits for a replacement task broker instead of running without credentials (closed port)` failed with `expected 'anonymous' to be 'reattached-run-credential'`.
- Failing before the second fix: the `(bridge unavailable)` and `(partly written broker file)` cases failed with `expected 'anonymous' to be 'reattached-run-credential'`. The `(closed port)` case passed.
- Failing before the third fix: `stops waiting for an unreachable task broker once its broker file is emptied` timed out after 20 seconds, because the launcher continued to wait. The `removed` case passed.
- Passing after the fixes: `npx vitest run packages/adapter-utils/src/github-launcher.test.ts packages/adapter-utils/src/execution-target.test.ts packages/adapter-utils/src/github-launcher-environment.test.ts server/src/services/heartbeat-github-launchers.test.ts server/src/services/native-runtime/native-github-access.test.ts` passed 138 of 138 tests in 5 files. `native-github-access.test.ts` includes the controller restart and launcher re-arm tests.
- `npx tsc --noEmit -p packages/adapter-utils` passed.
- I did not run the full `pnpm verify`. The local disk was too small for a full install.
- Note: Run these tests outside a managed sandbox, or remove the sandbox GitHub launcher from `PATH` and unset the sandbox broker variables. The sandbox values otherwise leak into the tests on `master` too.

## Risks

- If the broker does not return, a GitHub command that needs credentials now waits up to about 60 seconds (plus one 10-second request timeout) before it continues without credentials. Before, it waited about 1.5 seconds. Local Git commands do not ask the broker, so they do not wait.
- A broker that answers 503 for a long time (for example, when its credential lookup fails) also causes this 60-second wait. Then the launcher continues without credentials, as before.
- The launcher sends no credential in the new stderr line. The tests check that broker tokens do not appear in stderr.
- Low risk otherwise. The change is in the generated launcher source only.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code 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
- [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

🤖 Generated with [Claude Code](https://claude.com/claude-code)





Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:24:11 -06:00
84a529df4f fix(monitors): let low-trust reviewers schedule a self-wake on their own task (#22212)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use the `set_task_monitor` tool to save a timed follow-up
check on their task
> - Agents that run with the `low_trust_review` preset (for example,
pull request reviewers) cannot save this check
> - The tool requires company-wide `runtime:manage` access, and the
preset denies that access
> - Thus a reviewer must wait for a different event before it can
continue its review
> - This pull request lets the assignee save or clear a self-wake
monitor on its own task, and keeps the company-wide restriction
> - The benefit is that reviewers can continue their own review on time,
with no new company-wide access

## Linked Issues or Issue Description

**What happened?**

A `low_trust_review` agent calls `set_task_monitor` on its own
in-progress task. The call fails with this error: "low_trust_review
agents cannot use company-wide or privileged runtime:manage APIs by
default." The tool is advertised to the agent, but the agent cannot use
it. The agent cannot schedule its own follow-up check.

**Expected behavior**

The assignee can schedule or clear a monitor that only wakes itself on
its own task inside its trust boundary. Monitors that create recovery
tasks or escalate to the board stay denied. Company-wide
`runtime:manage` stays denied.

**Steps to reproduce**

1. Assign an in-progress task to an agent.
2. Start a native run for that task with a `low_trust_review` execution
policy whose boundary root is the task.
3. Call `set_task_monitor` with a future `nextCheckAt` and notes.
4. See the 403 error with reason `deny_low_trust_boundary`.

**Paperclip version or commit**

`master` at 8282d386da.

## What Changed

- `assertCanManageIssueMonitor` accepts an optional own-task scope. With
this scope, a `deny_low_trust_boundary` result for `runtime:manage` does
not block the assignee when both the requested monitor and the stored
monitor are the assignee's own self-wake (`wake_owner` recovery,
scheduled by the assignee, not the provider-quota service) or are empty.
- The native `set_task_monitor` tool passes this scope only when the
agent, project and task policies alone resolve the same low-trust
boundary as the current run. A monitor wake starts a run from those
sources, not from the run snapshot. Thus the woken run keeps the same
low-trust limits. A low-trust boundary that only the run snapshot
carries is still denied.
- The tool still checks `issue:read` and `issue:mutate` on the target
first, and still requires an in-progress or in-review task assigned to
the calling agent.
- The `create_recovery_issue` and `escalate_to_board` recovery policies
still require `runtime:manage`. The assignee also cannot clear or
replace a board-scheduled, recovery, escalation or provider-quota
monitor.
- The HTTP issue routes do not change.
- `doc/LOW-TRUST-PRESETS.md` describes the new rule.

## Verification

- Test 1 failing before the fix: `pnpm vitest run
src/services/native-runtime/task-monitor.integration.test.ts -t
"low-trust reviewer"` (in `server/`). The new test failed: `promise
rejected "Error: low_trust_review agents cannot use company-wide or
privileged runtime:manage APIs by default."` from
`assertCanManageIssueMonitor`, with `{ status: 403, details: { reason:
'deny_low_trust_boundary' } }`.
- Test 2 failing before the trust fix: `pnpm vitest run
src/__tests__/issue-monitor-scheduler.test.ts -t "low-trust limits"`. A
run with a low-trust policy only in its snapshot could save a monitor
(`promise resolved ... instead of rejecting`). After the fix, that call
is denied. When the task carries the policy, the monitor is saved, the
real scheduler fires it, and the woken run resolves to
`low_trust_review` with the same boundary.
- Test 3 failing before the stored-monitor fix: the extended "low-trust
reviewer" test cleared a board `escalate_to_board` monitor (`promise
resolved ... instead of rejecting`). After the fix, clear and replace
are denied for board-scheduled, `escalate_to_board`,
`create_recovery_issue` and provider-quota monitors.
- Passing after: `task-monitor.integration.test.ts`,
`issue-monitor-scheduler.test.ts` and
`native-preserved-monitor-wait.test.ts` pass (100/100).
- `pnpm run typecheck` in `server/` passes.
- I did not run the full `pnpm verify`.

## Risks

- Low risk. The change applies only to the native tool, only to the
assignee, and only to the task-scoped `wake_owner` monitor. A monitor
wake goes only to the same agent on the same task, and that run resolves
the same low-trust boundary.
- The bypass depends on the `deny_low_trust_boundary` decision reason.
Other denials (for example, a viewer responsible user, a task bridge
key, or a skill-test token) still block the call.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in an agent harness.

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1118.0-canary.827000
2026-11-18 15:19:11 -06:00
DottaandClaude Opus 5.5 8a295f944d fix(runner): fail fast when an artifact storage read stalls (#22210)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use the `download_artifact` tool to copy a saved API artifact
into their workspace
> - The server reads the artifact bytes from storage before it installs
the file
> - This storage read has no deadline. A stalled storage response or
stream keeps the tool call open
> - The provider MCP client stops the call after about five minutes with
the error "The operation timed out."
> - This pull request puts a 60-second deadline on the storage read and
returns a clear, retryable error
> - The benefit is that the agent gets a fast, clear result and can
retry, and does not wait for five minutes

## Linked Issues or Issue Description

**What happened?**
Some `download_artifact` calls stopped for four to five minutes. Then
the agent got only "The operation timed out." In one case, a retry of
the same 1 MB artifact completed in about 20 seconds.

**Expected behavior**
A stalled storage read must fail quickly. The error must tell the agent
that no file was written and that it can retry the same download.

**Steps to reproduce**
1. Give `PaperclipRunnerToolAuthority` a storage service whose
`getObject` never resolves, or whose stream sends one chunk and then
stops.
2. Call `download_artifact` for an artifact in that storage.
3. The call does not settle. Nothing aborts the storage request.

**Root cause**
`#readApiFile` called `storage.getObject(...)` without a `signal` and
read the stream with no deadline. Other storage reads in the runner, for
example chat attachment reads, already have a deadline.

## What Changed

-
`server/src/services/native-runtime/paperclip-runner-tool-authority.ts`:
the artifact branch of `#readApiFile` now uses a 60-second
`AbortSignal.timeout`. It sends the signal to `storage.getObject`. It
destroys the stream when the deadline expires. Every storage stream gets
an error listener before it can be destroyed, so a late reply cannot
raise an uncaught `AbortError`. It returns HTTP 504 with code
`artifact_storage_timeout` and the message "Artifact storage read did
not finish within 60 seconds. No file was written; retry the same
download."
- A new optional binding field, `storageReadTimeoutMs`, sets the
deadline for tests. The default is 60 seconds. The production callers do
not change.
-
`server/src/services/native-runtime/artifact-transfer.integration.test.ts`:
a new regression test covers a storage response that never arrives and a
stream that stops after one chunk.

## Verification

- Failing before the first fix: `cd server && npx vitest run
src/services/native-runtime/artifact-transfer.integration.test.ts -t
"stalls"` failed with `Error: Test timed out in 15000ms.` The
`download_artifact` call never settled.
- Failing before the late-reply fix: the same test now also covers a
storage reply that arrives after the deadline, with a real
`createReadStream` that gets the aborted signal. It failed with an
uncaught `AbortError` (`ABORT_ERR`).
- Passing after both fixes: the same command passes. Each stalled call
fails in less than 5 seconds with the retryable error. All storage
signals are aborted. No uncaught error occurs. The workspace has no
files.
- `npx vitest run
src/services/native-runtime/artifact-transfer.integration.test.ts
src/services/native-runtime/paperclip-runner-tool-authority.test.ts`: 49
passed.
- `npx vitest run
src/services/native-runtime/runner-api-artifacts.integration.test.ts
src/services/native-runtime/runner-api-artifacts.test.ts
src/services/native-runtime/issue-document-batch.integration.test.ts`:
38 passed (first revision).
- `pnpm run typecheck` (server): passed.
- `pnpm verify` selects a very large set of files for this module. I did
not run the full set locally. CI covers it.

## Risks

- Low risk. The deadline applies only to the artifact read from storage,
and artifacts are at most 10 MiB. A healthy read takes seconds.
- A very slow but working storage provider that needs more than 60
seconds for 10 MiB now gets a retryable error.
- The error occurs before any file write, so no partial file stays in
the workspace.
- This change does not fix a slow storage provider. It makes the failure
fast and clear.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), with tool use and code execution
in a sandboxed 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
- [ ] 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:14:46 -06:00
DottaandPaperclip ee68098584 fix(runner): keep current task requests readable in OpenCode traces (#21584)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Company traces let operators compare each request with its reply.
> - OpenCode limits each text field to 8 KiB.
> - A fresh session can put old history before the current request.
> - The limit can remove the current request from the trace.
> - This change selects the current task text first and links the
retained submission.

## Linked Issues or Issue Description

Refs #18098 and #18699. Neither merged change selects the current task
request.

**What existing behavior does this improve?**

OpenCode company traces can contain only part of the old session
history.

**Current behavior**

The exporter clips the full model envelope from its start. A sampled
trace has a useful HOLD reply but a request that ends inside old
history. A truncation flag is not proof that the task failed.

**Proposed behavior**

Select the task prompt before the text limit. Remove a valid leading
generated handoff packet from the excerpt. Link the full retained run
event through the existing API.

[Source
pattern](https://www.braintrust.dev/app/Paperclip/p/Paperclip%20Staging/patterns/e6d8da04-ca3e-4bd9-bd90-737f7717a9e1).

### Hypothesis and thesis for a fix

The baseline exporter spends its text budget on the envelope and old
history. The new regression confirms this cause: the received OTLP input
loses a short current request after a long handoff. Select the current
request in the OpenCode projection before redaction and clipping. Keep
storage and access checks with their existing owners.

## What Changed

- Select task identity and prompt for known native envelopes. Put
pending user messages first in continuation excerpts.
- Omit only a valid leading generated handoff packet. Keep plain text
and unknown formats on the existing path.
- Add a relative run-events reference under the prompt capture switch.
Readers must sign in to the source instance and page to the matching
turn.
- Keep raw tool argument values excluded. Keep redaction, opt-in,
capture switches, company access and size limits.
- Add exporter, proxy, installed-runtime and private-run retrieval
tests. Fix the proxy test's session-directory lookup so it skips the
output-custody directory.
- Document the excerpt and full-event retrieval path.

## Verification

- Baseline `6b6c94a4ea8f3d1b58767d67a7a2fc4ceaecda9c`: the new
long-handoff regression failed because OTLP input did not contain the
current request.
- Same regression passes after the fix. Exporter, redaction and bundled
proxy suites: 39 tests passed.
- `PAPERCLIP_OPENCODE_QUALIFY=1 pnpm --dir packages/paperclip-runner
exec vitest run
src/drivers/opencode/company-observability-runtime.test.ts`: 2 passed.
Real installed OpenCode 1.18.34 and real HTTP OTLP receiver; local SSE
model fixture. Both capture settings pass. The model receives the full
original submission.
- Private-run API suite: 31 tests passed on base
`340157d1d6ec01ad0fa55970e148c6cd332bbcb1` with these changes.
Authorized readers retrieve a complete request over 8 KiB through
pagination. Other readers receive 404.
- Runner TypeScript source and test checks and TypeScript build passed.
`git diff --check` passed.
- `pnpm verify --explain` returned exit 2 and required broader CI. No
full local-suite pass is claimed.
- Initial harness attempts used the wrong Vitest working directory,
lacked built plugin-sdk, selected the wrong proxy fixture directory, or
expected 403 instead of the API's 404. These are not red regression
results. The corrected checks above pass.
- Review follow-up `dfe995a77f3eb3280a6b081b4df9428fac85f540` removes
added code comments required by CONTRIBUTING.md. Exporter + installed
OpenCode runtime suites reran: 30 tests passed, with the local SSE model
and real HTTP OTLP receiver. `git diff --check` passed. The review
thread is resolved. Greptile passed on this exact revision with
confidence 5/5 and no actionable findings. Final-head typecheck, build,
Runner and E2E checks passed; server test shards and the amd64 Runner
image build remain in progress. No hosted model call or deployed
recovery is claimed.

## Risks

Known envelope excerpts change shape from serialized envelope text to
readable task text. The handoff selector depends on the current
generated packet format; unknown framing falls back to the full prompt
excerpt. Long current requests still clip. Full-event access depends on
source-instance permission and retention. Export remains best effort.
The new reference grants no access and includes no credential. This PR
is unmerged and not deployed.

## Model Used

OpenAI GPT-6 through Codex, with reasoning, tool use and code execution.
The exact serving variant and context size are not exposed to this
session.

## 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

Final verification (2026-11-14): exact head
`dfe995a77f3eb3280a6b081b4df9428fac85f540` has 60 successful checks, one
neutral security scan, and five conditional skips (cache write,
publication/attestation, incremental selection, Storybook paths).
Applicable typecheck, build, general and serialized tests, Runner tests,
E2E and both Runner image architectures passed.
[CI](https://github.com/paperclipai/paperclip/actions/runs/43572758306),
[Runner
images](https://github.com/paperclipai/paperclip/actions/runs/43572758233),
[Greptile](https://github.com/paperclipai/paperclip/runs/132380487679).
Greptile 5/5, no unresolved actionable findings. Unmerged and not
deployed.

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-18 15:08:04 -06:00
github-actions[bot]andlockfile-bot fcaf748607 chore(lockfile): refresh pnpm lockfiles (#22220)
## Thinking Path

> - Paperclip uses a dependency lock for reproducible builds.
> - Dependency changes on master need matching lock entries.
> - Paid eval reports also pin a reviewed offline correction.
> - Reports must install before paid model work starts.
> - This automated PR keeps the lock and report proof together.

## Linked Issues or Issue Description

**What happened?**

Dependency manifests on master changed after the last committed lock
refresh.

**Expected behavior**

Frozen installs must match those manifests. Eval reports must retain
matching offline lock proof.

**Steps to reproduce**

Run a frozen install before and after this lock refresh.

## What Changed

- Refresh the dependency lock from the manifests on master.
- Refresh the sandbox provider lockfiles from their manifests on master.
- Include the matching offline report correction and hashes.
- Resync the SDK public source proof's lock pins from the refreshed
lock.

## Verification

- Pinned pnpm resolution completed with lifecycle scripts disabled.
- The report proof refresh accepted the reviewed committed baseline.
- The workflow rejected changes outside the lock and report proof files.

## Risks

The lockfile bot merges this PR without CI or review when every added
package version is at least 3 days old on npm. Otherwise the PR waits
for a maintainer, and the daily refresh tries again. The bot merges only
the exact commit this workflow generated from manifests already reviewed
on master. Unknown report lock baselines remain blocked. This update
changes no permissions or paid enable gates.

## Model Used

None — generated by pnpm and the deterministic report-lock updater.

## Checklist

- [x] Thinking path and problem description included
- [x] Generated lock and matching report proof included
- [x] Release-age gate decides between bot merge and maintainer review

Co-authored-by: lockfile-bot <lockfile-bot@users.noreply.github.com>
2026-11-18 15:01:15 -06:00
DottaandClaude Opus 5.5 7f9c115cc2 fix(github): let a queued push start the next review turn instead of a blocker continuation (#22223)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A GitHub review bot reviews each PR in a task. Each push sends a new
review request to that task as a chat message.
> - A push that arrives during a review waits as a deferred chat wake.
That wake starts a new turn. The turn binds its tools to the newest
pushed commit.
> - #21959 and #22140 continue a run that reports a blocker in a fresh
session. That continuation keeps the source binding of the blocked run.
It also holds the task, so the waiting push request does not run.
> - On staging, a push during a review made the publication fail with
"requested for an older pull request head". The agent reported a
blocker. Paperclip then continued twice with the old binding. Each
continuation finished the review and could not publish it.
> - A second failure mode: a complete re-review that listed only the
files changed since the prior review got a short rejection. The
rejection named no files, and a small model stopped instead of
correcting the submission.
> - This pull request lets a queued chat request take the next turn
instead of a blocker continuation. It also names the missing files in
the coverage rejection.
> - The benefit is that reviews publish for the newest push without a
person, and agents can correct incomplete coverage on the next call.

## Linked Issues or Issue Description

**What happened?**
On staging, automatic GitHub reviews stopped publishing. The bots posted
"Publication is currently blocked" and "Paperclip must authorize the
review for <newest commit>". The run history showed this sequence: a
review run started for the first commit. Two pushes arrived during the
run. Steering into the active run was rejected for both pushes, so they
waited as deferred chat wakes. The run reported a blocker. Paperclip
then started two `native_environment_blocker` continuations. Each
continuation had no message of its own, so its GitHub tools resolved to
the first commit's request and refused the current head. The waiting
push requests did not run until a later push.

**What did you expect?**
A push request that waits behind a run starts the next turn, bound to
that push. The agent then reviews and publishes for the current head.

**Steps to reproduce**
1. Start an automatic review on a PR.
2. Push a new commit while the review runs, so the review request waits
as a deferred chat wake.
3. Let the run report a blocker (for example after the stale-head
publication refusal).
4. See that a fresh-session retry starts with the old binding and the
push request stays deferred.

Refs #21959, #22140, #22066

## What Changed

- `status-arbiter.ts`: new rule before the blocker continuation lanes.
When a blocked run has a queued chat request for the same task and
agent, the decision is `preserve` with only `release_checkout` (reason
`native_blocker_superseded_by_queued_request`). The normal release drain
then starts the queued request. A pause hold or a board-owned blocker
keeps the existing behavior.
- `native-runtime/queued-chat-request.ts`: new `hasQueuedChatRequest`
query. It uses the same chat-wake test that keeps chat wakes out of
first turns (`chatConversationId` or `externalChatProvider`).
- `native-run-finalizer.ts`: supplies `hasQueuedChatRequest` to the
arbiter, only for a blocked report.
- `chat-github-review-policy.ts` / `chat-github-reviews.ts`:
`githubCompleteCoverageGap` replaces the inline check. The rejection now
names the missing files (up to 20), says that a complete review covers
all changed files, and gives the two corrections (add them to
`reviewedPaths`, or submit `complete: false` with `omittedPaths`).

## Verification

- Red/green: `cd server && npx vitest run
src/services/native-runtime/native-environment-blocker.integration.test.ts`.
The new case failed before the fix with reason
`native_environment_blocker` and one scheduled retry, as on staging.
After the fix it passes: no retry, the task stays `in_progress`, and the
chat wake stays deferred for the release drain.
- Red/green: `npx vitest run
src/services/native-runtime/status-arbiter.test.ts -t "queued chat
request"`.
- Red/green: `npx vitest run
src/services/chat-github-review-policy.test.ts -t
githubCompleteCoverageGap`.
- `native-agent-blocker.integration.test.ts` and the full arbiter and
review-policy suites pass.
- `cd server && npx tsc --noEmit -p .` passes.
- `pnpm verify` on the changed files (results in the CI checks below).

## Risks

- Low to medium. The new rule changes only blocked reports that would
otherwise auto-continue while a chat request waits behind the run.
Without a waiting chat request, the behavior does not change.
- The waiting request now starts the next turn instead of the
continuation. If the blocker is real, that turn can report it again, and
the existing lanes apply.
- The finalizer does one more indexed read, only for blocked reports.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code with tool use: code
search, editing, shell, test runs, and staging run inspection through
the browser.

## 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 15:00:57 -06:00
911fe5bb9a Fix Recents ordering and add sidebar pins (#22219)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The sidebar gives people quick access to tasks, chats, and projects.
> - Recents should reflect the order in which a person opened their
tasks.
> - Opening a task only updated its saved details. It did not update the
visit time.
> - This pull request records task visits and adds Recents shortcuts to
the existing sidebar pins.
> - People can find their last task and keep frequently used items above
More.

## Linked Issues or Issue Description

**What happened?**

Opening a personal task left it in its old position or added it at the
bottom of Recents. The Recents rows also had no controls to pin their
items.

**Expected behavior**

Opening a task moves it to the top of Recents. Opening a nested task
moves its parent group to the top. A person can pin a task, chat, or
project from Recents.

**Steps to reproduce**

1. Open two personal tasks in the Coordinator workspace.
2. Reopen the first task and check its position in Recents.
3. Hover over a Recents row and look for a pin button.

**Paperclip version or commit**

Reproduced on source checkout `43b2d8be22`.

**Deployment mode**

Local dev with an isolated embedded PostgreSQL database.

Related work: #22024, #21649, and #19685.

## What Changed

- Record the first loaded task visit and subsequent reopens. Keep the
timestamp during background refreshes.
- Use the most recent task visit in each displayed group when ordering
parent rows.
- Add tasks, agent chats, and projects from Coordinator Recents to the
existing sortable sidebar pins. Resolve saved shortcuts with the current
company data and task read permissions.
- Use the same highlight state for a Recents row and its pin button.
This includes the current row, hover, and keyboard focus.

## Verification

- The reopen test failed before the fix because the older task stayed
below the newer task. The Chromium check also reproduced the missing pin
on the current row before the highlight fix.
- Ran the eight focused Vitest files for task detail, the two sidebars,
recent task state, task warmup, and pinned navigation on macOS. Ran
`pnpm --filter @paperclipai/ui typecheck`.
- In Chromium on the isolated dev server, opened two tasks and reopened
the first. Pinned a task and project and confirmed that both survived
reload. Checked current, hovered, and keyboard-focused rows. Checked
that a pointer click did not keep the pin visible after leaving an
inactive row.
- `pnpm verify` requested broader CI coverage because the product
documentation changed.

- GitHub CI passed on `b77fc06393`. The initial native-server and Canary
jobs lost their runners. Both jobs passed on retry without a code
change. [CI
retry](https://github.com/paperclipai/paperclip/actions/runs/44373716458/attempts/2)
- Greptile scored the same commit 5/5 and left no review threads.
[Greptile
review](https://github.com/paperclipai/paperclip/pull/22219#issuecomment-6988318333)

## Risks

- Recent ordering keeps the existing participation filter and subtask
groups. A task pin uses the existing summary batch to check read access
independently of participation.
- Pins are stored per browser user. Task and project keys include the
company ID. Existing page and agent-chat keys keep their saved order.
- The change uses the existing summaries API. It requires no schema
migration.

## Model Used

- OpenAI GPT-6 via Codex, with shell, GitHub CLI, and Chromium
verification 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 linked existing issues or described the issue using
the relevant issue template
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
Paperclip 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
- [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: Scott Tong <1504818+scotttong@users.noreply.github.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-18 12:52:37 -08:00
DottaandClaude Fable 5.2 33fac97cad feat(routines): ship the redesigned routine page and let live webhooks be tested again (#22205)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Routines start agent work on a schedule, from a webhook, or on
demand
> - The routine detail page split one routine across eight sections
behind a section sidebar (overview, triggers, variables, secrets,
delivery, runs, activity, history)
> - People had to hunt through sections to see what a routine does and
to change it, and a finished webhook could not be tested again without
starting the routine
> - This pull request makes the approved two-column routine page, one
Edit dialog and one Webhook dialog the real routed page, and lets a live
webhook go back into test mode
> - The benefit is one page that answers what the routine does, when it
runs, who runs it and what it made, with every change in one dialog

## Linked Issues or Issue Description

**Problem**
The routine detail page spreads one routine over eight sections and a
section sidebar. Changing a routine means visiting several sections,
each with its own save bar. A webhook that is already live cannot be
tested again: the API only accepts `setupPending: false`, so testing a
live webhook starts the routine.

**Proposed solution**
Ship the reviewed design (stories `routine-page-design`,
`routine-edit-dialog-design`, `routine-webhook-dialog-design`) as the
routed page in both UI shells, wired to the real API. Let `PATCH
/api/routine-triggers/:id` accept `setupPending: true` for a live
webhook so the next events are checked but never start the routine.

**Alternatives considered**
Keep the sections and restyle them. The owner rejected this: the section
sidebar should go.

## What Changed

- `/routines/:id` renders `RoutinePage` in both shells
(`RoutineDetail.production.tsx` is removed). Status switch, Repeats
rows, default agent, responsible user, project, Asks for, Secrets, Run
rules, Managed by plugin, Instructions with Show all, copy and the
comment count, and History.
- History is paged: 20 tasks per page from `GET
/companies/:id/issues?originKind=routine_execution&originId=…&sortField=created&sortDir=desc&limit=21&offset=…`,
with a real Load more. Coalesced runs show as "folded into a task".
- A failed refetch keeps the loaded page on screen (`useQueryView`); a
History failure shows `QueryErrorState` in place.
- Header: Edit, "…" (Version history, Audit log, Archive / Restore) and
Run now. In the streamlined desktop shell they sit in the breadcrumb
toolbar; elsewhere above the page.
- Version history (`/routines/:id/history`, restore and restored-webhook
keys kept) and Audit log (`/routines/:id/activity`,
`RoutineAuditActivity`) open as sub-views with a way back. Old section
addresses and `?tab=` redirect to `/routines/:id`.
- Edit dialog saves title, instructions, variables, secrets, agent,
project and responsible user in one request against the revision the
dialog opened with (save conflict shows "changed while you were
editing"). The first schedule is created, changed or removed after that.
Priority and delivery settings are never sent, so saved values stay.
- Webhooks are created, changed, tested and removed (with Undo) right
away from the Edit dialog, with the Webhook dialog nested inside it.
Closing the Webhook dialog ends setup or test mode. A webhook left in
test mode shows "Testing · events don’t run" on the page and offers
Finish testing.
- Responsibility (only with `enableResponsibilities`): the page shows
direct and through-project responsibilities from the link lookup; the
dialog links or unlinks the direct one. With the flag off nothing is
fetched or shown.
- The routines list creates routines with the same dialog in create
mode, filed in the open folder, and opens the new routine page.
- Server: `setupPending: true` on a live webhook enters test mode
(planned by a pure `planTriggerUpdate`, which also gives the activity
action) (422 for other trigger kinds; 409 for a disabled or removed
webhook or an archived routine). Test deliveries keep the last real
delivery as `lastWebhookDelivery.previous`, and finishing testing
restores it. Activity `routine.trigger_test_started`.
- Additions to the reviewed design, from review, so no capability is
lost: the schedule popover has Pause/Resume; standing-check and API rows
open a small popover with Pause/Resume and Remove; removing a trigger
from the page leaves a "… removed. Undo" line under Repeats. Stories:
`StandingCheckOpened`, `ScheduleTriggerPaused(Opened)`,
`RemovedWithUndo`.
- Save is several requests (routine, schedule, responsibility). It
changes only the schedule the form opened with, records each finished
step, and a partial failure says what was saved and that saving again
finishes it. The dialog cannot be dismissed while saving. Failed reads
show a Retry state, never empty choices.
- Removed: the routine section sidebar and contextual sidebar, the
trigger wizard, trigger cards, save bar, section components and their
tests.
- Storybook: the three routine stories moved to `stories/routines` as
current production stories, a new story mounts the routed page against a
fixture API, and stories that used the old page were updated or removed.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/routines-e2e.test.ts` (17/17) and
`src/__tests__/routines-service.test.ts` (105/105).
- `pnpm exec vitest run` on the routine page, routines list, routine
form, webhook instructions, Layout, shell navigation, audit and editor
tests: 275 tests pass.
- `cd ui && npx tsc -p tsconfig.json --noEmit`, `node
scripts/check-token-gates.mjs`, `node scripts/check-maps.mjs`, `node
scripts/storybook-catalog.mjs --check`: pass.
- `pnpm verify` exits 2 (global CI input changed); required CI supplies
the broad coverage.
- Manual: an isolated worktree instance (`pnpm paperclipai worktree init
--empty`, `pnpm dev`) with a seeded routine. Headless Playwright: an old
`/triggers` address redirects, no section sidebar, History shows 20 then
23 after Load more, the schedule popover opens, pause and resume, Edit →
Add webhook → created key → Finish, title save, Test webhook → Finish
testing, Version history, Audit log shows "Started testing a webhook",
phone width has no horizontal overflow, and Create routine from the list
opens the new page. No console errors or failed API calls.

## Risks

- Behaviour change: the section pages are gone. Old links redirect to
the single page.
- The delivery-setting editors (concurrency, catch-up, activity gate)
and priority are removed from the UI. Saved values stay, and the API
still accepts them.
- The create dialog no longer offers a folder picker or delivery
settings. A new routine goes into the folder the list is showing and
takes the default settings.
- Replace key in the Webhook dialog acts at once, as in the reviewed
design. The old confirmation is gone.
- No migration. `lastWebhookDelivery.previous` is an optional field
inside the existing jsonb column.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, in Claude Code with
tool use (shell, file edits, headless browser) and subagents for the
server change and the Storybook move.

## 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
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-18 13:13:15 -06:00
Devin FoleyandPaperclip f4d44ac13e fix(ui): keep GitHub identity widgets out of replies (#22217)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents call connected apps while they work on tasks.
> - Some app tools include a widget that Paperclip shows with the reply.
> - GitHub identity lookups include a profile widget. Repeated lookups
fill the reply with copies of the same card.
> - This pull request omits the known GitHub identity view when
Paperclip selects reply widgets.
> - The benefit is that task replies show useful app results while
identity calls remain in the tool history.

## Linked Issues or Issue Description

**What happened?**
A task that reads GitHub activity showed four copies of the connected
account's profile widget. Each copy came from a successful `get_me`
call. Paperclip showed these intermediate lookup results with the reply.

**Expected behavior**
GitHub identity lookups stay in the folded tool history. Other app
widgets keep their normal reply placement.

**Steps to reproduce**
1. Connect GitHub through its MCP server.
2. Run a task that calls `get_me` several times to find the connected
account.
3. Open the task reply. Each lookup adds a profile card.

**Paperclip version or commit**
Reproduced in the UI tests against base commit `8285a81280db`.

**Deployment mode**
Authenticated server. The rendering path is shared with local instances.

Related work: [MCP Apps
support](https://github.com/paperclipai/paperclip/pull/21119), [MCP Apps
reply views](https://github.com/paperclipai/paperclip/pull/21266).
Searched open issues and PRs for `get_me`, GitHub widgets, and MCP Apps.
No duplicate fix was found.

## What Changed

- Omit a view from the reply index only when its upstream tool is
`get_me` and its resource is `ui://github-mcp-server/get-me`.
- Apply the filter before the per-run widget limit. This covers saved
history and live replies through their shared index.
- Add tests for repeated saved identity calls, widget pagination, and
other GitHub and app views.
- Document the display policy in the MCP Apps guide.

The MCP Apps UI owns reply selection. Tool execution, view storage, API
responses, and the folded tool history keep their existing behavior.

## Verification

- Red-green reproduction: the three new regression tests failed before
the source change and passed after it.
- `pnpm exec vitest run ui/src/components/mcp-app/`: 6 files, 36 tests
passed.
- `pnpm --filter @paperclipai/ui typecheck`: passed after building the
worktree's missing SDK declarations with `pnpm --filter
@paperclipai/plugin-sdk ensure-build-deps`. The first typecheck failed
because those generated declarations were absent.
- `git diff --check`: passed. Reviewed the diff for secrets, personal
data, and run artifacts.
- `pnpm verify --explain`: exited 2 because the guide is a global CI
input. Required CI must supply broad coverage. An earlier selection was
invalidated by the guide edit and was rerun.
- Browser acceptance and a deployed staging check have not been run. The
saved-widget regression uses the shared React reply component.
- [Greptile
review](https://github.com/paperclipai/paperclip/pull/22217#issuecomment-6988213101):
5/5 for head `c842d21bff6de1b2084593abfff69e789775b163`, with no
actionable findings or unresolved review threads. Required CI is still
running.

## Risks

- Low risk. The display filter matches one known tool and resource pair.
Other widgets remain visible.
- This release hides GitHub profile cards even when a task intentionally
calls this tool to read a profile. The text result remains in the tool
history.
- No schema migration or stored-data cleanup is required. Existing saved
cards disappear from replies after the updated UI loads.

## Model Used

- OpenAI GPT-6.1 Sol (`gpt-6.1-sol`) through Codex in T3 Code, with
xhigh reasoning effort, tool use, and code 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
- [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>
2026-11-18 11:11:51 -08:00