Commit Graph
8117 Commits
Author SHA1 Message Date
DottaandClaude Opus 5.5 10ddb26dbb test(server): accept dash's exit code for a sandbox-denied shell write (#21792)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Runner workspace bridge runs agent commands in a `bwrap` sandbox
that binds only `/usr`, `/bin`, `/lib` and the task workspace
> - A server test checks that a sandboxed command cannot read or write a
file outside the workspace
> - The test only runs where `/usr/bin/bwrap` exists. CI jobs that the
gate sends to GitHub's `ubuntu-latest` now get the `ubuntu-26.04` image,
which has `bwrap`, so the test runs on CI for the first time
> - There it fails on every run, because it expects the write attempt to
exit with 1, but Ubuntu's `/bin/sh` (dash) exits with 2 when a
redirection fails
> - This pull request checks that the write fails and that the file is
unchanged, without depending on the shell's exit code
> - The benefit is that the "General tests (server (7/12))" job passes
again on the new image, and the test still proves the sandbox denial

## Linked Issues or Issue Description

**What happened?**
`server/src/services/native-runtime/runner-bridge-tools.test.ts` ›
`Runner workspace bridge > runs useful commands but denies files outside
the workspace and injected credentials` fails in "ci / General tests
(server (7/12))" on unrelated branches, on the first run and the retry:
- PR #21765, head `98197c87e9`
- branch `feat/run-loop-detector`, run 43732047843, head `b8c6e27429`,
job 132866487949, image `ubuntu-26.04` version 20261111.196.1

```
AssertionError: expected { exitCode: 2, signal: null, …(3) } to match object { exitCode: 1 }
 ❯ src/services/native-runtime/runner-bridge-tools.test.ts:180:19
```

On jobs that ran on the RunsOn `ubuntu24` image there is no
`/usr/bin/bwrap`, so the test is skipped (7 skipped instead of 6).

**Expected behavior**
The test passes wherever the command sandbox is available, and it fails
if the sandboxed command can read or change the outside file.

**Steps to reproduce**
1. In a Debian or Ubuntu container, run `/bin/sh -c 'printf stolen >
"$1"' sh /nonexistent/dir/private.txt`.
2. dash prints `cannot create /nonexistent/dir/private.txt: Directory
nonexistent` and exits with 2. bash exits with 1. `cat` of the same path
exits with 1.
3. In the sandbox, the outside temporary directory is not bound, so the
path does not exist. This is the same case.

**Root cause**
A stale test expectation, exposed by a CI image change. No commit on
`master` changed the bridge, the sandbox or this test today (the last
change to the test is from 2026-11-08). The test expected the shell
write to exit with 1. That is bash behavior. On Ubuntu, `/bin/sh` is
dash, which exits with 2 for a failed redirection. Until today no CI
image had `bwrap`, so the test never ran on CI.

**Production impact**
None. The sandbox denies the access as intended: the `cat` step on the
same run exits with 1 and its output does not contain the secret, and
the write fails with `Directory nonexistent` because the outside
directory is not visible in the sandbox. This is not a sandbox
regression.

## What Changed

- The write step now checks that the outside file still contains
`PRIVATE` first, then that the command was not stopped and exited with a
non-zero code. It no longer requires exit code 1 from the shell.
- The read step and the success step are unchanged.

## Verification

- Linux container (`node:24-bookworm-slim`, `/bin/sh -> dash`): the
write command exits with 2 under dash and 1 under bash, and both are
failures, as the test now accepts.
- `npx vitest run
src/services/native-runtime/runner-bridge-tools.test.ts` in `server/` on
macOS: 11 passed, 6 skipped (the sandbox tests need Linux with `bwrap`).
- I cannot run the sandbox test on this Mac. It runs in this pull
request's CI only when the job lands on an `ubuntu-26.04` runner.

## Risks

- Low risk. Only one test assertion changes. The test still fails if the
write succeeds, because the file content check runs first and the exit
code must be non-zero.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edit, GitHub CLI, Docker).

## 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-15 10:47:19 -06:00
DottaandClaude Opus 5.5 3ee6049f71 perf(native-runtime): name why a preinstalled provider pack was not reused (#21781)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A remote agent run needs the provider pack (Node, OpenCode and the
Runner bridge) inside its sandbox before the provider can start
> - The server reuses a pack that is already installed in the sandbox
image, or it uploads its own pack
> - In a recent load test every task uploaded the pack, and this step
was about 43% of the time to first token
> - The compatibility check and the preinstalled-pack verification
failed, but the run records did not say which check failed
> - This pull request records the failed check on the run's performance
spans
> - The benefit is that the next run names the reason, so the image or
the check can be fixed without guesswork

## Linked Issues or Issue Description

**What existing behavior does this improve?**
The run performance spans for provider pack selection. Today a failed
`provider_pack.compatibility` or `provider_pack.verify_preinstalled`
span only says `outcome: failed`. The code catches the error and drops
it.

**Subsystem affected**
Server: native runtime, remote provider pack selection
(`server/src/services/native-runtime`).

**Current behavior**
`provider_pack.select` records `reason: cached_packs_unverified` when it
uploads. The compatibility check throws one generic message for about
ten different conditions, and the caller swallows it. The remote
verification script throws a generic `manifest mismatch` without the
fields that differ.

**Proposed behavior**
Each failed check has a short, fixed name (for example
`installation_unprotected`, `contract_digest`, `artifact:nodeCommand`,
`manifest_mismatch:runnerSourceRevision`). The trace records this name
as the `check` attribute on the failed span. `provider_pack.select`
records the last preinstalled rejection as `check` when it uploads. The
compatibility span records `target: image` or `target: workspace`.

**Reason and benefit**
Upload of the provider pack costs about 15 s per task on the test
instance. To remove it, we must know which check rejects the image pack.
The attribute holds only fixed check names and manifest field names,
never paths or values.

**Breaking changes**
None. Error messages keep their existing text. The upload decision does
not change.

## What Changed

- `remote-provider-pack-verification.ts`: the compatibility check names
the failed condition (`failureCheck`). The remote verification script
prints a fixed `paperclip-pack-check=<name>` line, and for a manifest
mismatch it names the differing manifest fields. Missing files now give
a named check instead of a raw stack trace.
- `native-run-trace.ts`: a failed `measure` records the error's
`failureCheck` as the safe `check` attribute.
- `remote-provider-pack.ts`: `provider_pack.select` records the last
preinstalled rejection (or `no_preinstalled_pack`) when it uploads.
- `native-session-executor.ts`: the `provider_pack.compatibility` span
records `target`, the preinstalled-pack selection passes its rejection
callback, and a failed link has the `link_failed` check. No other lines
change.

## Verification

- `cd server && npx vitest run
src/services/native-runtime/native-run-trace.test.ts
src/services/native-runtime/remote-provider-pack.test.ts
src/services/native-runtime/remote-provider-pack-verification.test.ts
src/__tests__/redaction.test.ts` passes (131 tests).
- Red/green: with the source changes reverted and the new tests kept, 12
tests fail. With the changes, all pass.
- The verification test runs the real remote script in a Node process: a
provenance-only difference gives
`manifest_mismatch:runnerSourceRevision`, a wrong artifact gives
`artifact_digest:nodeCommand`, and a missing manifest gives
`manifest_unreadable`.
- `npx tsc --noEmit -p server/tsconfig.json` passes.

## Risks

- Low risk. The change adds diagnostics only. The selection order, the
checks themselves and the upload path do not change.
- The `check` attribute is filtered by the existing safe-attribute list
and a strict character pattern, so it cannot carry paths or secrets.

> 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`) 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
- [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-15 10:46:33 -06:00
DottaandClaude Opus 5.5 46e5e4450f fix(runner): leave an undispatched tool call to the next controller on restart detach (#21786)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Paperclip Runner keeps an agent session alive while its
controller restarts, for example during a deploy, and the next
controller adopts it
> - A Paperclip tool call can be between its committed input and its
handler when the controller detaches
> - In that window the old controller journaled "The turn stopped before
this operation was dispatched" as the final, non-retryable result, but
the turn did not stop
> - The agent then got a false failure for a call that never ran, and
the next controller could not recover the call. A restart must never
fail work
> - This pull request leaves that call unsettled for the next
controller, the same as a call that was already in its handler
> - The benefit is that a controller restart no longer turns an agent's
pending tool call into a permanent error, and a CI test that failed on
four pull requests now passes deterministically

## Linked Issues or Issue Description

**What happened?**
`src/live/runnerd-codex-transport-orphaned-tool-at-attach.test.ts` ›
`settles an earlier generation's in-flight tool call at attach even when
that attach never finishes startup` failed in "ci / Verify Paperclip
Runner (vitest package (3/3))" on 2026-11-15. In each job the first try
and the CI retry both failed:
- PR #21757, head `d04825d812`, job 132824209377
- PR #21713, head `7758d56719`, job 132681892394
- PR #21729, head `c63a05a013`, job 132732839971

Every failure is the same, at line 74, right after
`detachControllerForRestart()`:

```
AssertionError: expected [ { …(8) } ] to deeply equal []
+   "type": "semantic_tool.result", "status": "pending",
+   "result": { "error": { "code": "semantic_tool_not_dispatched",
+     "message": "The turn stopped before this operation was dispatched.", "retryable": false } }
```

**Expected behavior**
When a controller detaches for restart, a tool call that it has not
dispatched stays unsettled. The next controller recovers it at attach,
the same as a call that is in its handler.

**Steps to reproduce**
1. Hold the semantic tool dispatch at a gate after the Runner commits
the tool input.
2. Call `detachControllerForRestart()`, then release the gate.
3. On `master`, the control-plane state has the
`semantic_tool_not_dispatched` result above. It is byte-identical to CI
(same command id and payload). The new test case `(still before dispatch
at detach)` does this.

**Root cause**
This is a Runner defect, not a test timing problem.
`#detachControllerOnce` sets `#closed`, resolves the closed signal and
resolves the turn-start admission with `false`. A call in
`#handleSemanticToolInput` that has not reached the handler then throws
`SemanticToolNotDispatchedError`. The durable control plane turns that
error into a journaled `semantic_tool_not_dispatched` result. That
result is correct when the turn stops. It is false when the controller
only detaches for restart, because the Runner and the turn continue. The
old test waited only for the committed input, so on a loaded CI runner
the detach sometimes came before the handler call.

**Production impact**
Yes. During a controller restart or deploy, an agent tool call in this
window got a non-retryable "turn stopped" error after the Runner was
adopted, and the next controller did not recover the call.

## What Changed

- `durable-prp-control-plane.ts`: new `SemanticToolHandedOffError`. When
the dispatcher rejects with it, the control plane journals no result.
The input stays unsettled for the next controller.
- `runnerd-codex-transport.ts`: the semantic tool callback goes through
`#dispatchSemanticToolInput`. If the call ends as not dispatched after
the transport detached for restart, it throws
`SemanticToolHandedOffError`. A normal close still journals
`semantic_tool_not_dispatched`.
- `runnerd-codex-transport-orphaned-tool-at-attach.test.ts`: the test
waits for the exact stage instead of the committed input. It runs two
cases: the call is in its handler at detach, and the call is held before
dispatch across the detach. Both then check the existing attach recovery
and the final `completed` result.

## Verification

- Red on `master`: the `(still before dispatch at detach)` case fails
every run with the CI assertion and payload.
- Green on this branch: `npx vitest run
src/live/runnerd-codex-transport-orphaned-tool-at-attach.test.ts` passes
2/2.
- Loop on macOS with 4 extra busy-loop processes (load average about 13
before them), 50 runs each: this branch 50/50 (100 test cases). The old
`master` test was 50/50 locally too, so the local loop does not show the
CI interleaving. The gate does.
- All 36 runner test files that use `detachControllerForRestart` or
`SemanticToolNotDispatchedError`: 1180/1182 pass with 3 workers under
load. The 2 failures (`runnerd-codex-transport-settlement.test.ts` and
`runnerd-acpx-source-reconciliation.test.ts`, `kill EPERM`) pass 36/36
when run alone.
- `npx tsc -p tsconfig.json --noEmit` and `npx tsc -p tsconfig.test.json
--noEmit` pass in `packages/paperclip-runner`.
- The other two static-check flakes from the same day are test-only and
are fixed in a separate pull request.

## Risks

- Medium-low risk. This changes Runner restart behavior for one window.
A call that was not dispatched now goes to the next controller's
recovery (`recoverSemanticToolInput`) instead of getting a final error.
That is the same path that already handles a call in its handler, so no
new recovery code is involved.
- If no successor ever attaches, the input stays unsettled. That is the
same state as for a call that was in its handler at detach.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edit, 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
- [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-15 10:27:04 -06:00
DottaandClaude Opus 5.5 7a9177af0f test(runner): remove coreutils and pid-file timing assumptions from static checks (#21787)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Paperclip Runner package has a "static checks" CI job that runs
`node --test` script tests
> - Two of these tests failed on unrelated pull requests on 2026-11-15
and passed on re-run
> - Each failure costs a re-run of the failed jobs and delays merges,
and it teaches people to re-run instead of read
> - One test assumed that a copied `/bin/sleep` acts as `sleep` under
any name. The other read a pid file before the child finished writing it
> - This pull request removes both assumptions, and one more instance of
the second pattern in the same test family
> - The benefit is that these tests no longer depend on the runner image
or on process scheduling

## Linked Issues or Issue Description

**What happened?**

1. `scripts/stage-runner-binary.test.mjs` failed in "ci / Verify
Paperclip Runner (static checks)" on PR #21765, head `98197c87e9`, job
132850068174:
- `atomically publishes while the previous executable is running`:
`AssertionError: 1 !== null` at line 124 (`old.child.exitCode`), after
77 ms.
- `a source rebuild selects fresh dev bytes ...`: `Expected "actual" not
to be strictly deep-equal` (line 192).
- That job ran on a GitHub-hosted `ubuntu-26.04` image (20261111.82.6).
The same tests pass on the RunsOn `ubuntu24` image, for example job
132822472729.
2. `scripts/materialize-kimi-distribution.test.mjs` › `setup
cancellation physically stops an in-flight owned child` failed in the
same job on PR #21758, head `40e38fc28a`, job 132822472729:
`AssertionError: The real child did not start` after 149 ms.

**Expected behavior**
The tests pass on every supported runner image and on a loaded runner.

**Steps to reproduce**
1. stage-runner-binary: in a Linux container, replace `/bin/sleep` and
`/bin/echo` with one multicall binary that picks the utility from
`argv[0]` and exits 1 for an unknown name (this is how uutils coreutils
works on Ubuntu 26.04). Run `node --test
scripts/stage-runner-binary.test.mjs`. On `master` both tests fail with
the CI messages, 20 of 20 runs.
2. kimi: make the child create the pid file, wait 300 ms, then write the
pid. On `master` the test fails with `The real child did not start` in
about 125 ms, the same as CI.

**Root cause**
1. On Ubuntu 26.04, `/bin/sleep` and `/bin/echo` are the same uutils
multicall binary. The test copies it to `paperclip-runnerd` and runs it.
The binary sees `argv[0] = paperclip-runnerd`, finds no utility of that
name, and exits 1. The fresh-build fixture (a copy of `echo`) also has
the same bytes as the old artifact (a copy of `sleep`), so the "fresh
bytes" assertion fails too.
2. The child wrote the pid with `writeFileSync`, which creates the file
and then writes it. The test loop broke on the first successful read. An
empty read gave `Number("") === 0`, so the loop stopped and the
assertion failed. The loop also had a fixed budget of 100 polls of 10 ms
for a Node child to start.

**Production impact**
None. Only tests change. The staging code works with any executable. The
Kimi setup cancellation code is correct: the deterministic repro shows
that the child is stopped once the test reads a real pid.

## What Changed

- `stage-runner-binary.test.mjs`: the test helper passes `argv0` to
`spawn`. The copied `sleep` runs with `argv0: "sleep"`, so a multicall
binary still acts as `sleep`. The fresh-build fixture is now a copy of
`/bin/sh` and runs `-c "exit 0"`, so its bytes always differ from the
old `sleep` artifact.
- `materialize-kimi-distribution.test.mjs`: the child writes `pid.tmp`
and renames it to `pid`, so a read never sees a partial file. The test
waits until the pid is valid or the command settles. The 3 s command
timeout and 5 s test timeout are unchanged.
- `provision-kimi-package.test.mjs`: the wait for the `download-ready`
marker continues until the child exits, instead of a fixed 1 s budget.
The existing 5 s kill timer still bounds it.
- No retries, skips or timeout changes.

## Verification

- stage-runner-binary, Linux container (`node:24-bookworm-slim`) with a
multicall `sleep`/`echo` built from a 15-line Go program that dispatches
on `argv[0]`:
  - `master`: 0/20 pass, same two assertions as CI.
  - this branch: 50/50 pass.
  - this branch with stock coreutils, and on macOS: all 9 tests pass.
- kimi setup cancellation:
  - delayed-write repro: `master` fails, this branch passes.
- loop on macOS, `master` test without extra load: 59/60 (one natural
failure). This branch: 60/60.
- loop with 4 extra busy-loop processes (load average about 13 before
them): `master` 100/100, this branch 100/100.
- `node --test scripts/stage-runner-binary.test.mjs
scripts/materialize-kimi-distribution.test.mjs
scripts/provision-kimi-package.test.mjs`: 19 pass, 1 skipped (public
download test, opt-in).
- The other CI flake from the same day,
`runnerd-codex-transport-orphaned-tool-at-attach.test.ts`, is a Runner
defect. It is fixed in a separate pull request.

## Risks

- Low risk. Only tests change.
- The rebuild test now uses `/bin/sh` as the fixture for the fresh
build. This file exists on every supported Linux and macOS runner.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edit, GitHub CLI, Docker).

## 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.1115.0-canary.15
2026-11-15 10:13:19 -06:00
DottaandClaude Opus 5.5 d14a3b88b1 fix(native): release an idle warm session whose Runner is proven gone, and retry a failed idle close (#21782)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A warm agent session keeps its Runner alive in a sandbox between
turns. The server closes idle sessions, and closes them again before it
exits.
> - When an idle close failed, the idle-timer path kept the session
registered and never tried again, unless the sandbox lease was already
inactive.
> - The controller-restart path tried once more, but it accepted no
proof that the session was already gone. It checked a destroyed sandbox
only for a forced environment delete.
> - In a release-swap test, one idle close failed with
`runner_remote_process_identity_unavailable`. The session stayed
registered until shutdown, the shutdown close failed again, and the
sandbox was held until the host stopped it.
> - This pull request treats a failed close as complete when the Runner
is proven gone or the sandbox is stopped or destroyed, retries a failed
idle close a bounded number of times, and logs which Runner check
failed.
> - The benefit is that a dead warm session is released, and the next
failure names its cause.

## Linked Issues or Issue Description

Refs #21627

**What happened?**
In a zero-downtime release-swap test, a warm session's idle close failed
4 s after the server left new run starts. The failure was
`runner_remote_process_identity_unavailable`. The idle-timer path kept
the session registered with no retry. At SIGTERM,
`closeIdleWarmNativeSessionsForRestart` tried again and failed the same
way. The log showed "idle warm native sessions did not close" and the
restart-chaos harness counted a warm-shutdown failure. The log did not
say which Runner check failed, so the cause of the unreadable identity
is not known.

**Expected behavior**
A close whose Runner is proven gone, or whose sandbox is stopped or
destroyed, releases the session. A failed idle close is tried again a
bounded number of times. The failure text names the Runner check stage
and reason.

**Steps to reproduce**
1. Keep a warm remote session idle.
2. Make its close fail with a `RemoteRunnerRecoveryError` (for example,
`process_verification/process_not_running`).
3. Call `closeIdleWarmNativeSessionsForRestart()`. On master the result
is `failed: 1`.

## What Changed

- `server/src/services/native-runtime/native-session-executor.ts`:
- New `warmCloseFailureProvesOwnerGone`. It uses existing proofs only:
the close error's Runner diagnostic is
`process_verification/process_not_running`, or a lease row for the
sandbox has a termination receipt (`hasRemoteTerminationReceipt`) with
state `destroyed`, or the warm run's own lease row has a receipt with
state `stopped`. `pending_cleanup` and a lease without a receipt prove
nothing. A lease read error counts as no proof.
- `closeIdleWarmNativeSessions` (controller restart, environment delete,
idle sleep) uses this proof for every failed close, not only for a
forced environment delete. A released Runner detach failure is
unchanged.
- The idle-timer path uses the same proof. Its earlier status-only rule
from #21504 (any lease status other than `active` or `retained`) is
removed, because `pending_cleanup` is written before the provider stop.
Without proof, it re-arms the timer and tries again, every 5 s, at most
3 times (`WARM_IDLE_CLOSE_RETRY_MS`, `WARM_IDLE_CLOSE_MAX_RETRIES`). The
log line records the attempt number.
- `describeWarmCloseFailure` appends the Runner check as
`[stage/reason/lifecycle]` when the error carries one.
- `server/src/services/native-runtime/native-session-executor.test.ts`:
three tests.
- "an idle warm session whose close fails with
runner_remote_process_identity_unavailable and whose Runner is proven
gone is released at controller restart"
- "names the Runner check in a warm close failure and keeps an unproven
owner registered at controller restart"
  - "retries a failed idle warm close a bounded number of times"
- The #21504 idle-path test is now "forgets a warm owner whose idle
close failed only once its sandbox has a stop or destroy receipt". A
stop or destroy receipt releases the owner. `pending_cleanup`,
`released` without a receipt, and `retained` keep it.
- "reads the warm owner's own lease rows at controller restart" (a stop
receipt for this run releases the owner; `pending_cleanup`, no receipt,
or another run's receipt do not)

## Verification

- `cd server && npx vitest run
src/services/native-runtime/native-session-executor.test.ts`: 1519
passed, 7 skipped.
- Red on master (with only the two exported constants added so the file
compiles): all three new tests fail. The first fails with `"failed": 1`.
- `npx tsc --noEmit -p server`: no errors.

## Risks

- A session is released without a checkpoint only when its Runner is
proven gone or its sandbox is stopped or destroyed. The last saved
checkpoint stays the recovery source, which is the same as the forced
environment delete path today.
- Environment delete and idle sleep now also accept the proof. Before,
they accepted only a destroyed receipt during a forced delete.
`pending_cleanup` is written before the provider stop, so it never
counts as proof here.
- The idle retry adds at most 3 more close attempts per failed session,
5 s apart.
- A failed idle close whose sandbox stop is still pending now keeps its
owner until a receipt lands or a successor retires it. Before, the
status alone released it.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used in Claude Code
with tool use (shell, file edit) and extended thinking.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [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-15 10:09:32 -06:00
DottaandClaude Opus 5.5 171e70c11d refactor: drop span and run-log event catalogs from the observability docs (#21779)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `doc/observability.md` and `doc/run-log-events.md` described every
OpenTelemetry span and every run-log event
> - `rules/data-paths.mdc` told authors to update
`doc/run-log-events.md` for each event, so both files only grew: 2,313
and 1,263 lines
> - Each span and event is already defined next to the code that writes
it, and its name is a literal string that a search finds in one step
> - This pull request removes the per-span and per-event catalogs and
keeps only what code does not say
> - The benefit is two short docs that do not drift from the code, and
no rule that makes them grow again

## Linked Issues or Issue Description

Refs #21670, #21700, and #21743 (the same cleanup for other docs).

**Issue type**

Outdated or confusing documentation.

**Where is the issue?**

`doc/observability.md`, `doc/run-log-events.md`, and
`rules/data-paths.mdc`

**What's wrong?**

The two docs repeated span names, span attributes, and event payloads
that the code defines. Operator setup started at line 138 of
`doc/observability.md`. The rule required a doc edit for every new
run-log event.

**Suggested fix**

Keep operator setup and the Sentry privacy contract. Point to the code
for span and event definitions. Remove the rule line that requires a doc
entry per event.

## What Changed

- `doc/observability.md` is now 619 lines. It keeps: how to enable
tracing, `service.version` resolution, scope, how to enable Sentry, DSN
delivery, environment attribution, privacy settings, server request
data, the core of "Run failure context", browser data, fail-open
behavior, the default capture set, and operator responsibilities. Kept
text is unchanged except the intro and two sentences noted below.
- Deleted from `doc/observability.md`: budget, Slack receipt, task
detail, and browser tracing notes; controller preparation phases; native
Runner spans; sandbox startup spans; sandbox duplex transport; shared
skill preparation; invocation attribution; and about 500 lines of
per-failure detail in "Run failure context".
- Replaced that per-failure detail with one paragraph. It names the
failures that `unexpected` mode keeps out of Sentry, and says the
remaining diagnostic contexts are defined in `server/src/sentry.ts`.
"Default capture set" now says the same.
- `doc/run-log-events.md` is now 23 lines. It says what the run log is,
where events are defined and appended, and keeps the payload storage
note.
- `rules/data-paths.mdc`: the run-log line now says to define an event
where it is written, not in a doc. The span-allowlist line now says the
allowlist is in the code that opens the span. The review levels and
globs do not change.
- Repointed links in two feature maps, two agent-access map files,
`tests/runner-e2e/SUITES.md`, `doc/runner-api-tools.md`, and the
Telemetry README. Updated the `honeycomb-tracing` skill and one code
comment in `packages/adapter-utils/src/http2-bridge-server.ts`.

## Verification

- A script built the new `doc/observability.md` from line ranges of the
old file and asserts the first line of each range.
- A link check on all changed Markdown files found 0 missing files and 0
missing anchors. The remaining inbound anchors (`#enabling-tracing`,
`#sentry-error-monitoring`) still exist.
- No test reads either doc.
- `node scripts/check-maps.mjs` passes.
- `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail.
- `pnpm verify` was not run. This worktree has no installed
dependencies. The only code change is a comment.

## Risks

- The privacy contract no longer lists each run-failure diagnostic
context field. `server/src/sentry.ts` is now the list. A reviewer of a
Sentry change must read that file.
- No browsable list of span names or run-log event names remains. A
search for the quoted name finds the producer.
- `.greptile/files.json` still scopes `rules/data-paths.mdc` to both
docs. Both files still exist, so it does not change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Claude Code desktop, with tool
use. Earlier analysis in this session used Claude Fable 5.2.

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

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 10:06:05 -06:00
DottaandClaude Opus 5.5 531db3c10b perf(db): keep dedicated connections for the next burst (#21769)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - One server process runs every agent on one Node main thread, and
each new database connection costs a TLS handshake, about 0.36 ms of
SCRAM key derivation on that thread, and a type-fetch query
> - `withDedicatedDbConnection` gives lock holders a private session;
since #21693 it keeps at most 4 released sessions and closes the rest
> - When the same burst of more than 4 dedicated holders comes back,
every holder above 4 opens a new connection again
> - A harness on embedded PostgreSQL measured 504 new connections per
1,000 uses for bursts of 8 and 760 for bursts of 16
> - This pull request keeps released dedicated clients for reuse while
idle plus in-use clients stay within
`DATABASE_DEDICATED_CONNECTION_MAX`; the driver idle timeout still
closes their sessions when they are not used
> - The benefit is 8 and 16 new connections per 1,000 uses for the same
bursts, with no change to any pool maximum or to
`databaseConnectionBudget()`

## Linked Issues or Issue Description

**What is the problem?**
A staging measurement showed `SET
application_name='paperclip-runner-checkpoint'` at 3.17/s and `SET
application_name='paperclip'` at 3.86/s with 7 live runs. This looked
like connection churn. The investigation found two separate facts:

1. The `SET` statements are not new client connections. postgres.js
sends `application_name` in the startup packet, never as a `SET`
statement (`StartupMessage` in postgres.js `src/connection.js`).
PgBouncer in transaction mode sends `SET application_name` itself when
it gives a client transaction a server connection that a client with
another `application_name` used last. With one shared server pool, every
checkpoint transaction that lands after a main-pool transaction costs
one `SET`, and the reverse. The rate follows checkpoint transactions,
not connects. The checkpoint pool opens at most 3 connections per 1,000
saves (measured below).
2. Dedicated connections did churn by construction for recurring bursts
of more than 4 holders (measured below). This pull request fixes that.

**Steps to reproduce**
Run `packages/db/src/connection-reuse-census.test.ts`. It counts
`pg_stat_database.sessions` around 1,000 operations.

**Expected behavior**
A recurring burst reuses the sessions that the previous burst opened.

## What Changed

- `withDedicatedDbConnection` keeps a released client idle when fewer
than `DEDICATED_CONNECTION_IDLE_MAX` (4) are idle, as before, or when
idle plus in-use clients stay within the dedicated limit
(`DATABASE_DEDICATED_CONNECTION_MAX`, default 24). A client whose action
failed, an ended client and clients after shutdown are still closed.
- Each retained client keeps the main pool's `idle_timeout` (default 60
s), so its session closes after that idle time, as the main pool's do.
The next use reconnects.
- The worst case stays at `2 x DATABASE_DEDICATED_CONNECTION_MAX + 4`: a
new client opens only when no client is idle, and a client is kept above
4 only while idle plus in-use is within the limit.
`databaseConnectionBudget()` and every pool maximum are unchanged.
- New `connection-reuse-census.test.ts` measures connections opened per
1,000 checkpoint saves and per 1,000 dedicated uses.
- `dedicated-connection-pool.test.ts`: the burst test now checks that
the next burst reuses all sessions and that they close after the idle
timeout (1 s in the test). Before, it checked that at most 4 stayed
open.
- `doc/DATABASE.md` describes the new retention rule.

## Verification

Connections opened per 1,000 operations, embedded PostgreSQL,
`pg_stat_database.sessions` (load average about 10.5 on a shared
machine):

| Operation | Before | After |
| --- | --- | --- |
| Checkpoint saves, concurrency 1 / 7 / 24 | 1 / 3 / 3 | 1 / 3 / 3 |
| Dedicated uses, steady concurrency 1 / 4 / 8 / 16 | 1 / 4 / 8 / 16 | 1
/ 4 / 8 / 16 |
| Dedicated uses, recurring bursts of 8 | 504 | 8 |
| Dedicated uses, recurring bursts of 16 | 760 | 16 |

- `pnpm --filter @paperclipai/db exec vitest run
src/connection-reuse-census.test.ts
src/dedicated-connection-pool.test.ts
src/dedicated-connection-admission.test.ts src/client-options.test.ts`:
38 passed. The burst cases fail on `master` (504 and 760 against a bound
of 8 and 16).

## Risks

- After a burst, up to `DATABASE_DEDICATED_CONNECTION_MAX` dedicated
sessions stay open for up to `DATABASE_IDLE_TIMEOUT_SECONDS` (60 s)
instead of closing at once above 4. This stays inside the connection
budget. With `DATABASE_IDLE_TIMEOUT_SECONDS=0` they stay open until
shutdown, like the main pool.
- Retained sessions keep the existing rule: actions keep session state
transaction-scoped.
- The PgBouncer `SET application_name` statements stay. Removing them
needs one shared `application_name` for all pools, which removes the
per-pool names that operators and tests use. That is a separate
decision.

## Model Used

- 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-15 09:51:55 -06:00
DottaandClaude Opus 5.5 8f1d39da79 perf(server): cache the instance settings row per process (#21768)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - One server process runs every agent on one Node main thread, and
each database statement costs main-thread time
> - The `default` instance settings row is read on hot paths: live run
event delivery, run log redaction, the stranded-task recovery check,
runner tool calls, adapter routes and run preparation
> - A staging measurement with 7 live runs showed the full-row settings
read at 10.24 statements per second, and 3.5 to 5.4 per second when idle
> - The row changes only when an admin or a boot step writes it, so
almost every read returns the same value
> - This pull request adds a per-process read-through cache for that
row, with in-process invalidation on every write and a 2 second age
bound for changes made by another process
> - The benefit is at most one settings read per 2 seconds per server
process, whatever the load

## Linked Issues or Issue Description

**Is your feature request related to a problem?**
The full `instance_settings` row read (`select id, singleton_key,
default_environment_id, general, experimental ...`) runs at 10.24
statements per second on staging with 7 live runs, and 3.5 to 5.4 per
second at idle. It scales with run events and recovery checks, not with
settings changes.

**Describe the solution you would like**
Cache the row per process. Drop the cached row when a settings write
commits, in this process and, through the existing work-signal
notification, in the other process during a deploy overlap. Bound the
age of a cached row to 2 seconds, so any other change (a direct database
edit, a second process outside an overlap) takes effect within 2
seconds.

**Describe alternatives you have considered**
A database trigger with LISTEN/NOTIFY would also catch direct edits, but
it needs a migration, and work notifications cross processes only during
a deploy overlap today. The existing signal plus a 2 second bound keeps
the change small.

## What Changed

- New `server/src/services/instance-settings-cache.ts`: a read-through
cache keyed by the database client. Concurrent misses share one read. A
cached row is at most `INSTANCE_SETTINGS_CACHE_TTL_MS` (2000 ms) old,
measured from the start of the read. Every caller gets its own copy.
Reads through a transaction handle skip the cache.
- `instanceSettingsService` `get`, `getGeneral` and `getExperimental`
use the cache. Write paths (`update`, `updateGeneral`,
`updateExperimental`, and the feedback vote save) still read the row
fresh.
- Every settings write publishes an `instance-settings-changed` work
signal through the existing work-signal channel
(`@paperclipai/db/work-signals`). Inside a transaction it is the first
signal of the write, so its `pg_notify` payload goes out before the
other wakes of the same commit (for example `status-card-evaluation`).
This process drops the cached row when the write commits. During a
deploy overlap, when work notifications cross processes, the other
process drops its cached row on receipt, before a worker woken by the
same write reads the settings. A reconnect of the notification listener
also drops the row.
- `fillUnsetInstanceDefault` writes through `update({ db: tx })`, so its
signal is sent when its transaction commits.
- A read that starts before an invalidation never stores its result, so
an old value can not come back after a write.
- The test setup clears the cache before each test, because many tests
write the row directly.

Hot callers of the cached row:

- Live run event delivery: `live-run-event-redaction.ts`
(`censorUsernameInLogs`), once per delivery batch.
- Run output and run lifecycle redaction: `heartbeat.ts`
`getCurrentUserRedactionOptions`, used by `run-output.ts`,
`run-lifecycle.ts`, `run-completion.ts`.
- The stranded-task recovery check: `recovery/service.ts` reads
`getExperimental().enableAgentChat` once per checked conversation issue.
- Runner tool calls: `paperclip-runner-tool-authority.ts`
(`enableIsolatedWorkspaces`, `enableExternalObjects`).
- Adapter routes: `app.ts` (`enableNativeRunner`, `enableOpenAiDot`) per
request.
- Run preparation: `heartbeat.ts` (`instance_settings` preparation
step), `queued-run-line.ts`, `queued-run-dispatch-liveness.ts`,
`run-control.ts`.
- Issue and comment paths in `issues.ts` (`censorUsernameInLogs`,
`enableAgentChat`).

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/instance-settings-cache.test.ts` (embedded PostgreSQL):
- 150 hot reads (`getGeneral`, `getExperimental`, `get` from new service
objects) after one warm read: 0 statements. Without the cache the same
test measures 150 statements (red run).
  - 20 concurrent misses: 1 statement.
- `updateExperimental` and `updateGeneral` are visible at once to a new
read in the same process.
- `fillUnsetInstanceDefault` (transaction write of the default
environment) is visible at once after it returns.
- A change written by a second client (another process) becomes visible
within 2000 ms plus a 500 ms test margin.
- A caller that changes the returned object does not change the cached
row.
- A read through a transaction handle sees the transaction's uncommitted
write, two such reads issue 2 statements, and the cache does not keep
the write after rollback.
  - A read that started before an invalidation is not stored.
- A received `instance-settings-changed` notification from another
process drops the cached row (next read issues 1 statement).
- `updateExperimental({ enableStatusCards: true })` sends
`instance-settings-changed` as its first notification, before
`status-card-evaluation`; `updateGeneral` sends it alone.
- The server tests that use instance settings or write the row directly
(230 files): see the run notes in the first comment.

## Risks

- A direct database edit, or a change from a second process outside a
deploy overlap, takes up to 2 seconds to apply in this process. Before
this change it applied at the next read. This includes access flags such
as `enableOwnerInstanceAdmin` (read per cloud-tenant request) and the
default environment.
- A change made through the settings service applies at once in this
process, and during a deploy overlap at once in the other process.
- A new code path that writes the `default` row must call
`announceInstanceSettingsChange`, or its change applies within 2
seconds.
- No schema change.

## Model Used

- 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
- [ ] I have updated relevant documentation to reflect my changes (no
user-facing setting or command changed)
- [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-15 09:50:19 -06:00
DottaandClaude Opus 5.5 3706f520fd test(scaling): keep ramping through recovered runs, read spend from cost records, and wait for termination before deleting agents (#21776)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The scaling effort uses a real-agent ramp harness
(`scripts/scale-agents-ramp.ts`, #21695 and #21757) to load a hosted
test instance through the product API
> - Its first run with agents that really ran (10 agents, 105 tasks, 106
runs) stopped on one failed run, recorded $0 model spend, and left
cleanup errors
> - Read-only inspection of the instance showed three harness faults.
The failed run had a same-run bootstrap retry scheduled 33 s later, but
the harness stopped and cleaned up first. Run rows carry no cost, but
cost records do (63.7 cents for the run's agents). Terminated agents
leave the company agent list, so the harness treated them as done and
sent deletes that Paperclip refused with 409
> - These faults make the ramp stop too early, make its spend cap inert,
and make cleanup report the wrong cause
> - This pull request keeps the ramp going through runs that Paperclip
recovers by itself, reads spend from cost records, records board latency
per route, and makes cleanup wait for termination and name what it left
behind
> - The benefit is that the next ramp grades the product, not the
harness, and its spend cap works

## Linked Issues or Issue Description

Refs #21695
Refs #21757

**What happened?**
The ramp stopped at step 1 with `failed_runs_zero failed (observed 1)`.
The run failed with `runner_ingress_bind_conflict` before its provider
session opened. Its run events show `same-run resume persisted` with
`recoverable: true` and `nextAttemptAt` 33 s later. The harness stopped
within 9 s and paused the agents, so the retry was blocked
(`native_retry_admission_ineligible`). The result showed `Recorded model
spend: $0`. The harness read `costUsd` from run rows, which is always
null; `GET /api/companies/<id>/costs/by-agent` holds 63.71 cents over
104 cost events for the 10 agents. Cleanup reported two `DELETE
/api/agents/:id returned 409: Complete termination before deleting the
agent`. Those agents were still `lifecycleState: terminating`; the
harness waited on the company agent list, which hides terminated agents,
so it treated them as done. A later `--cleanup-only` changed nothing
because it also found agents only through that list. The board API p90
failed (765 ms), but the result had no per-route timings to say which
request was slow.

**Expected behavior**
A failed run whose task finishes by itself is counted, not a stop. A
failed run whose task does not finish within a grace stops the ramp. The
share of failed runs is graded at the step end. Spend comes from
Paperclip's cost records. Cleanup deletes an agent only after
termination completes, and names the agents and sandbox leases still
pending.

**Steps to reproduce**
1. Run `node --test scripts/scale-ramp/scale-ramp.test.ts` with the new
fake and tests and the `origin/master` `ramp.ts`, `cleanup.ts`,
`criteria.ts` and `report.ts`.
2. 16 tests fail, among them every new test (recovered run, unrecovered
run, spend from cost records, spend cap, board per route, termination
wait, still-terminating agents and `--cleanup-only`, leases released
during the wait).
3. With this change, all 60 pass.

**Paperclip version or commit**
Instance on `2026.1106.0+2564.git.3244780bd`; harness from #21757.

## What Changed

- `criteria.ts`: replace `failed_runs_zero` with
`failed_runs_unrecovered_zero` (immediate) and `failed_run_rate` (at the
step end). Step metrics add `runsEnded`, `runsFailedRecovered`,
`runsFailedUnrecovered`, `runsFailedPending` and `board.byRoute`.
- `ramp.ts`: a run counts as failed once it was seen `failed` or
`timed_out`. It is recovered when its task reaches `done`. It is
unrecovered when the task rests not done, needs Retry, or has no live
run for `--recovery-grace-minutes` after the failure. A task whose
interruption has an automatic retry scheduled (`state: retry_scheduled`,
`nextRetryAt` or `retryWait`) does not count as needing Retry. Spend
comes from `costs/by-agent` for the run's agents on each poll, and each
step reports the spend in its window. Board probes keep a distribution
per route.
- `config.ts`: add `--max-failed-run-percent` (default 2) and
`--recovery-grace-minutes` (default 15).
- `cleanup.ts`: read agents by id as well as from the list, so
terminated agents in the state file are found. Wait for `lifecycleState`
`terminated` or `rejected` by id before a delete. Report
`agentsStillTerminating`, `activeSandboxLeaseIds` and
`sandboxLeasesReleasedDuringWait`, and name each lease still active with
its run and acquire time.
- `report.ts`: the summary shows recovered, unrecovered and pending
failed runs, board latency per route, and each cleanup error.
- `fake-paperclip.ts`: run rows carry no cost; `costs/by-agent` returns
cents per agent. Optional failure of the n-th run, a scheduled recovery
run, a termination delay (terminated agents leave the list and a delete
answers 409 until termination completes), and leases that stay active
after their run.
- `doc/plans/2026-11-13-thousand-concurrent-agents.md`: the runbook
describes the failed-run criteria, the spend source and the cleanup
behavior.

## Verification

- `node --test scripts/scale-ramp/scale-ramp.test.ts`: 60 of 60 pass.
- Red check: with the new fake and tests but the `origin/master`
`ramp.ts`, `cleanup.ts`, `criteria.ts` and `report.ts`, 16 tests fail,
including all 8 new ones.
- `tsc -p scripts/scale-ramp/tsconfig.json`: no errors.
- Evidence from read-only GETs on the test instance: run `f1892d43`
events (bind conflict, scheduled same-run retry, blocked after the
pause), run rows (`costUsd` null on all 106), `costs/by-agent` (63.71
cents for the 10 agents), agent rows by id (`terminating` while absent
from the list), lease rows.
- Not run: a new real ramp (needs the owner's go-ahead).

## Risks

- Low risk. The change touches only the scale-ramp harness, its fake,
its tests and one runbook section. No product code changes.
- A failed run no longer stops the ramp at once. An unrecovered one
stops it after the grace (15 min by default), so a broken step can run
up to that long. The step-end failed-run rate still fails a step with
more than 2% failed runs.
- Spend now needs cost read access for the board token. If
`costs/by-agent` cannot be read, the result reports spend as not
measured and the spend cap does not trigger.
- Cleanup can now take up to 5 more minutes while it waits for
termination by id.

## Model Used

Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, read-only HTTP GETs to the test instance).

## 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-15 09:39:28 -06:00
DottaandClaude Opus 5.5 2b23119ed2 fix(native): keep a warm follow-up that inherited its predecessor's process identity waiting on the same run (#21774)
## 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.
> - #21697 makes a follow-up wait while that outgoing server is still
alive, instead of starting a second Runner over its session.
> - Runtime selection copies the warm predecessor's process fields
(`processPid`, `processGroupId`, `processStartedAt`) onto the follow-up
and records `inheritedProcessIdentityRunId`.
> - The wait records itself with `deferNativeControllerRecovery`. That
function refused any run with process fields, so it refused every warm
follow-up that the wait stopped. The run failed with
`native_controller_recovery_wait_authority_changed`.
> - This pull request lets the deferral accept an inherited identity,
and clears those inherited fields in the same transaction so the usual
resumption claim can pick the run up.
> - The benefit is that a warm follow-up in a deploy overlap stays on
the same run and does not fail.

## Linked Issues or Issue Description

Refs #21697

**What happened?**
In a zero-downtime release-swap test, a follow-up comment arrived 0.25 s
after its predecessor finished on the outgoing server. The follow-up run
started on the incoming server 1.09 s later.
`waitForLiveWarmSessionOwner` found the outgoing server alive and asked
to wait. `deferNativeControllerRecovery` then refused with
`native_controller_recovery_wait_authority_changed`, because the run
carried the process fields that runtime selection copied from its warm
predecessor. The run failed after 2.7 s with
`native_continuation_requires_reconciliation`. Held recovery started a
fresh run. The task finished, but the run history shows one failed run.

**Expected behavior**
A warm follow-up whose only process identity is inherited from its
predecessor waits on the same run. The resumption owner claims it at the
deadline. A run whose own process has started is still refused.

**Steps to reproduce**
1. Run a warm remote agent turn on server A.
2. Switch new run starts to server B while A still serves.
3. Post a follow-up within about 1 s of the turn's finish.
4. The follow-up fails with
`native_controller_recovery_wait_authority_changed`.

## What Changed

- `server/src/services/native-runtime/native-controller-recovery.ts`
(`deferNativeControllerRecovery`):
- Process fields refuse the deferral only when they are the run's own.
Fields count as inherited when
`runnerProfileJson.inheritedProcessIdentityRunId` is set and the run has
no own `native.process_start_requested` or
`native.process_identity_recorded` event. `run-cost-accounting.ts` uses
the same proof.
- With an inherited identity, the same transaction clears `processPid`,
`processGroupId` and `processStartedAt`. It keeps
`inheritedProcessIdentityRunId`. `claimNativeSessionResumptions`
requires those fields to be null.
-
`server/src/services/native-runtime/native-controller-recovery.integration.test.ts`
(real Postgres):
- New: "keeps a warm follow-up that inherited its predecessor's process
identity on the same run until the outgoing owner's deadline".
- Two new cases in "does not publish an admission wait after authority
changes": `own-process` (process fields, no marker) and
`inherited-then-own-process` (marker plus an own process-start event).
Both stay refused and keep their fields.

## Verification

- `cd server && npx vitest run
src/services/native-runtime/native-controller-recovery.integration.test.ts
-t "inherited its predecessor|does not publish an admission
wait|unstarted follow-up"`: 9 passed.
- Red on master: the new test fails with `Error:
native_controller_recovery_wait_authority_changed`. The own-process
cases pass on master and with the change.
- Green: the run is `retryable_failure` with `nextAttemptAt` at the
deadline, its process fields are null, no claim happens before the
deadline, and one claim happens at the deadline.

## Risks

- The follow-up now waits instead of failing. The wait ends when the
outgoing server saves a suspended checkpoint, when it exits, or at the
predecessor's finish plus its idle window plus 2 minutes. In the
observed case, the outgoing server's idle close could not save its
checkpoint (`native_runner_checkpoint_owner_lost`), so the wait would
end only when that server exits. See the follow-up note below.
- An own process is still refused. The proof uses the run's own
process-start events, the same proof as run cost accounting.

**Follow-up note (not in this PR):** The outgoing server's checkpoint
write checks the task's current run. A native successor that is parked
in this wait is not one of the accepted successor kinds, and the idle
close is not retried. So the wait does not end early from a checkpoint.
In the observed timeline, the wait is about 225 s (until the outgoing
server exited). The worst case with the default 5-minute idle window is
about 425 s.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used in Claude Code
with tool use (shell, file edit) and extended thinking.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [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-15 09:19:23 -06:00
DottaandClaude Opus 5.5 b9cf64f5bf test(server): check the agent row lock with FOR SHARE so lock checks cannot block each other (#21775)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Each master commit must pass Cloud readiness before its canary and
image publish
> - `agent-file-restore-locking.test.ts`, added in #21694, failed master
Cloud readiness run 43712563988 on 2026-11-15, so that commit's canary
did not publish
> - The test reported the agent row as locked during the download, but
its own sampler measured 0 ms of product lock time
> - The cause is in the test: its two lock checks used `FOR UPDATE
NOWAIT` on one pool and could block each other
> - This pull request checks the lock with `FOR SHARE NOWAIT`, which
still detects the product's `FOR UPDATE` but never conflicts with
another check
> - The benefit is that the test fails only when the product really
holds the lock

## Linked Issues or Issue Description

**What happened?**
`downloads a stale projection without holding the agent row lock` failed
in master Cloud readiness run 43712563988, attempt 2:
`expected [{ objectKey, agentRowLocked: true }] to deeply equal [{
objectKey, agentRowLocked: false }]`.
The test's metric line showed `lockedMs: 0`.

**Steps to reproduce**
1. Make each sampler check hold its `FOR UPDATE NOWAIT` lock for 50 ms
(to make the overlap certain).
2. Run `pnpm exec vitest run
src/__tests__/agent-file-restore-locking.test.ts -t "stale projection"`
in `server/`.
3. The test fails 3 of 3 times with `agentRowLocked: true` and
`lockedMs: 0`, the same as CI.

**Expected behavior**
Only a lock held by the product makes the check report "locked".

Refs #21694

## What Changed

- `agentRowLocked()` uses `FOR SHARE NOWAIT` instead of `FOR UPDATE
NOWAIT`. The product takes `FOR UPDATE` on this row
(`agent-file-store.ts`, `agent-instruction-revisions.ts`), which
conflicts with `FOR SHARE`. Two `FOR SHARE` checks do not conflict.
- New test: three concurrent checks all report unlocked, a `FOR UPDATE`
held on another connection is reported locked, and the row reads
unlocked again after release.

## Verification

- Red: with the forced 50 ms overlap and the old `FOR UPDATE` probe, the
test failed 3 of 3 runs with the CI error.
- Green: with the same forced overlap and `FOR SHARE`, 4 of 4 tests
passed in 3 of 3 runs.
- Final file (no forced overlap): `pnpm exec vitest run
src/__tests__/agent-file-restore-locking.test.ts` in `server/`: 5 of 5
tests passed in 5 of 5 runs.

## Risks

- Low risk. Test-only change. The new test makes sure the check still
detects a real `FOR UPDATE` lock.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, 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
- [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-15 09:15:45 -06:00
DottaandPaperclip 62033b9994 fix(qa): schedule recovered cleanup promptly and wait for task panels (#21660)
## Thinking Path

> - Paperclip lets people manage AI agents and their saved work.
> - QA journeys check browser controls and the cleanup of owned agent
resources.
> - A recovered workspace queues sandbox destruction after its files are
saved.
> - The cleanup queue treated that first attempt as a retry and waited
five minutes.
> - Agent termination correctly waited for destruction, so QA cleanup
failed first.
> - This PR runs that first cleanup attempt promptly and keeps the
existing safety gates.
> - It also waits for task-panel transitions before the browser acts
again.

## Linked Issues or Issue Description

**What happened?**

The full scheduled QA smoke completed with 23 passed and 1 failed.
Stop/redirect passed all eleven behavior checks but failed cleanup. The
cancelled run had a saved workspace and a bound stop receipt before
agent termination. Its sandbox was destroyed about five minutes later.
The shared cleanup schedule applied the retry delay before the first
destruction attempt.

The browser regressions also found that the current panel helper can
consume all four actions while an opener remains visible during panel
mounting.

**Expected behavior**

A recovered workspace's first cleanup attempt runs on the next eligible
worker pass. A failed attempt retains normal backoff. Agent termination
still waits for completed resource cleanup. Task-panel navigation waits
for the next controls before it acts again.

**Steps to reproduce**

1. Queue recovered-workspace destruction after the cleanup worker has
become idle.
2. Read the next cleanup deadline and advance one normal worker pass.
Before this fix, the deadline is five minutes late and no teardown runs.
3. Open task document controls with a delayed side-panel transition.
Before the panel fix, both collapsed-panel controls fail.

Refs #19224 and #19292 for retaining stop proof during workspace
recovery. This change keeps the full cleanup requirement for agent
termination. Current master supplies the shared task-panel helper; this
branch uses it and retains additional browser regressions.

## What Changed

- Use one shared first-attempt predicate for the cleanup deadline, sweep
selection and ownership report. It now includes recovered workspace
cleanup bound to the same run.
- Preserve worker spacing, in-flight claims, ownership and saved-file
checks, retry delays and attempt limits.
- Wait for panel controls after opening the panel. Wait for the selected
tab or menu action to finish.
- Add real PostgreSQL cleanup regressions, keep the Chromium controls,
and document the cleanup timing.

## Verification

Tested on Linux x86_64, Node v25.9.0. Local commit
`7c8e0f12aa4b19aaf53669141ab3299ce76db963` and published head
`892c5dd4b4638796a138400d8bbe30aee19c71dd` have the same tree,
`d135a98bdff58e3320cdc83976ffe1cf47f48b66`.

- Red: both new real-PostgreSQL cleanup tests failed on the old code.
The deadline was five minutes late and the first normal sweep made zero
teardown calls.
- Green: 87 cleanup, ownership and lifecycle tests pass. The
restored-work case stays unconfirmed until the real cleanup worker
destroys the lease; failure still backs off and the worker becomes idle
again.
- Red after master integration: both delayed document-panel browser
cases failed. Green: all 18 Chromium support checks pass.
- 77 journey contract tests pass.
- Product E2E typecheck passes with the documented low-memory path. The
initial ordinary attempt was killed by the local memory limit and is not
counted as a pass.
- The only follow-up after the passing checks removes new code comments
to follow the contribution guide. Runtime and test behavior are
unchanged. Final-head [CI run
43714742904](https://github.com/paperclipai/paperclip/actions/runs/43714742904)
completed successfully at this exact head. All 63 PR checks are
terminal: 58 success, 2 neutral and 3 conditional skips; no failures or
pending checks. Typecheck, build, tests and the final verify gate pass.
Greptile and Paperclip Review both score this head 5/5 with no
actionable findings; both historical inline threads are resolved.
- Hosted QA recovery is still unverified. No extra model run, merge,
deployment or QA setting change was made.

## Risks

Recovered workspace destruction starts sooner. Existing producer,
file-preservation, ownership, claim and provider checks still decide
whether teardown is allowed. Failed attempts retain the existing
cooldown. Agent termination and purge gates are unchanged. The panel
helper waits for visible controls and still fails when controls or saved
values are absent.

The PostgreSQL integration uses a controlled provider boundary. It does
not prove a new live Daytona or deployed QA pass. That requires the
fixed revision on QA and a later normal scheduled smoke.

## Model Used

OpenAI GPT-6-based Codex, with tool use and code execution. The host
does not expose a more specific model ID or context-window size for this
run.

## 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 references)
- [x] My branch name describes the change 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-15 08:52:49 -06:00
DottaandPaperclip afca556728 fix(github): clarify configured review task completion (#21748)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - GitHub bots publish reviews and report the result of their assigned
task.
> - A GitHub check and a Paperclip task have separate completion rules.
> - The current prompt explains how to wait, but gives little completion
guidance.
> - A bot can keep a complete review in review while it waits for CI or
merge that its assignment does not require.
> - This pull request makes the configured completion rules clear in
GitHub prompts.
> - The benefit is a finite review task with an accurate status and
publication evidence.

## Linked Issues or Issue Description

Related change: Refs #17318 keeps advisory review waits separate from
human attention. This change adds completion guidance in the same GitHub
prompt owner.

**What happened?**

A bot can publish a complete current-head 5/5 review and still wait for
CI or merge. Manual request prompts also lack the task completion
guidance used by automatic reviews.

**Expected behavior**

When the configured assignment allows completion at 5/5, a complete
published review can finish Done. CI and merge are completion conditions
only when the assignment requires them. Explicit tracking rules still
apply.

**Steps to reproduce**

1. Configure an agent to finish after a complete published current-head
5/5 review.
2. Start a GitHub review with CI results unavailable.
3. Inspect the generated prompt. It explains a response wait but does
not explain this completion case or publication safeguards.
4. With this change, automatic, mention, and comment prompts carry the
same explicit guidance.

**Paperclip version or commit**

Base commit: `83541e89ad3b90740ffc61a32c396dddb5834526`.

**Deployment mode**

Built from source. The prompt change applies to GitHub bot tasks.

## What Changed

- Add shared guidance within the GitHub prompt module for configured
completion at 5/5 and finite discussion replies.
- Require a complete assessment, confirmed publication, and the current
head in the 5/5 guidance.
- Preserve explicit CI, merge, and below-5 tracking rules. Keep the
shared status arbiter and check thresholds unchanged.
- Add six prompt cases. State that CI is unavailable in the existing
lifecycle completion case.
- Document the configuration example and its limits.

## Verification

- Six new prompt cases failed before the change.
- `pnpm exec vitest run
server/src/services/chat-github-review-policy.test.ts`: 40 passed.
- `pnpm exec vitest run
server/src/services/native-runtime/external-chat-wait.integration.test.ts
-t 'settles a published'`: 9 passed.
- `pnpm exec vitest run
server/src/services/native-runtime/external-chat-wait.integration.test.ts
-t 'inherits.*review|published.*guard|unknown publication|pending
publication|changed head|inherited.*review'`: 5 passed.
- `git diff --check` passed.
- `pnpm verify` returned exit 2. The connector document requires broader
CI coverage.
- Local preflight installed dependencies and built shared and plugin SDK
packages. It stopped because Cargo is unavailable. Full local typecheck,
build, and test suites were not run.
- [Greptile reviewed this
commit](https://github.com/paperclipai/paperclip/pull/21748#issuecomment-6894002401)
at 5/5 with no actionable findings. Its check passed for
`36dd146cdc00b0f3d7f6fc2971f24166ef0f6bf5`.
-
[CI](https://github.com/paperclipai/paperclip/actions/runs/43711597984)
passed for `36dd146cdc00b0f3d7f6fc2971f24166ef0f6bf5`. Typecheck, build,
Rust/Runner, all server tests, and all eight E2E test groups passed. The
final [CI
gate](https://github.com/paperclipai/paperclip/actions/runs/43711597984/job/132808715297)
passed at 12:17:58 UTC on 2026-11-15.
- At 12:23 UTC, all 61 check records were complete: 57 passed, 1 was
neutral, and 3 were skipped. Snyk also passed. No checks failed or
remained pending.

## Risks

This change gives prompt guidance. It does not enforce a score-to-status
rule. Custom assignments can still require CI, merge, or later review.
The focused tests check prompt content and existing lifecycle behavior;
they do not prove every live agent or webhook journey.

## Model Used

OpenAI GPT-6 through Codex, with reasoning, tool use, and code
execution. This session does not expose the exact model variant or
context window size.

## 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 described the issue in this PR with the bug report fields
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My public branch name describes the change and contains no
internal 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 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-15 08:52:01 -06:00
DottaandClaude Opus 5.5 e6562755e1 fix(issues): cover a blocked issue whose own run is queued after its blockers finish (#21770)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A parent task is blocked on its subtasks. When the last subtask is
done, Paperclip queues a run for the parent to continue.
> - The board marks a blocked task "needs attention" when no live work
covers it. The check looks at the blockers, then at each blocker's runs.
> - When every blocker is done, the check returned "needs attention" at
once. It did not look at the parent's own queued or running run.
> - In a release-swap test, a parent showed "needs attention" for about
12 minutes while its own continuation run waited in the queue. Nobody
had to do anything. The state cleared by itself.
> - This pull request makes the check return "covered" when the blocked
task has its own queued or running run.
> - The benefit is that people see no false "needs attention" while
Paperclip already continues the work.

## Linked Issues or Issue Description

Refs #21731

**What happened?**
In a zero-downtime release-swap test, a blocked parent task had two
subtasks. Both subtasks were done. Paperclip queued the parent's
"children completed" run, which waited about 12 minutes for a free agent
slot. During that time, `blockerAttention` was `needs_attention` /
`attention_required`, with 0 unresolved blockers and the parent itself
as the terminal blocker. The board showed the parent in the blocked
inbox. Then the run started, finished, and the parent became done.

**Expected behavior**
A blocked task whose own run is queued or running is covered by live
work. It must not ask a person for attention.

**Steps to reproduce**
1. Create a blocked parent task with one or more subtasks that block it.
2. Mark every subtask done.
3. Keep the parent's own run queued (for example, when the agent has no
free slot).
4. Read the parent from the issue list. `blockerAttention.state` is
`needs_attention`.

## What Changed

- `server/src/services/issues.ts`: in `readIssueBlockerAttentionBatch`,
when a blocked root has no unresolved blockers, the function now checks
the active-issue set that it already built. If the root has its own
queued or running run (or an active wake), it returns `covered` with
`blockingTreeLive: true`. Otherwise it returns `needs_attention` as
before.
- The change adds no query. The active-issue set already includes the
roots, through their `executionRunId` and their wake requests.
- `server/src/__tests__/issue-blocker-attention.test.ts`: two tests.
- "classifies a blocked parent whose children are all done as covered
while its own children-completed run is queued"
- "keeps a blocked issue with no unresolved blockers and no active run
as needs_attention"

## Verification

- `cd server && npx vitest run
src/__tests__/issue-blocker-attention.test.ts`: 29 passed.
- Red on master: the first new test fails with `"state":
"needs_attention"`. Green with the change.
- The second new test passes on master and with the change (negative
case).

## Risks

- Low risk. The change only affects a blocked task with zero unresolved
blockers. That task now reads as covered while its own run is queued or
running. When the run ends without a status change, the task reads as
`needs_attention` again.
- The covered result has no reason (`reason: null`), because no blocker
covers it. The UI label is then "Blocked", not "waiting on 0 sub-tasks".

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used in Claude Code
with tool use (shell, file edit) and extended thinking.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [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-15 08:51:38 -06:00
DottaandPaperclip 5b750fdf25 feat(ui): add foldable sidebar subtasks with bounded refreshes (#21649)
## Thinking Path

> - Paperclip helps people manage AI agents for work.
> - The sidebar helps people return to recent tasks.
> - Recent parents need foldable child tasks.
> - Busy companies must not refresh every child group for unrelated
work.
> - Exact unread counts must preserve personal reads and task access.
> - This pull request adds child groups and bounds their refresh work.
> - People can scan subtasks without repeated background requests.

## Linked Issues or Issue Description

**Subsystem affected**

Task navigation in the standard and Classic sidebars.

**Problem or motivation**

Recent parent tasks did not show their subtasks. The first
implementation refreshed every previously viewed group. One unrelated
update caused 52 child-page requests and one summary request after
viewing 50 groups. Exact child counts also repeated privacy and unread
checks per child.

**Proposed solution**

Show direct subtasks with independent folding and ten-row pages. Refresh
affected groups and summary batches. Stop offscreen reads. Bound
child-request concurrency. Aggregate viewer facts once and preserve the
existing inbox unread rule.

**Roadmap alignment**

This extends existing task navigation. The existing feature PR is reused
for its performance repair. No new PR duplicates it.

## What Changed

- Add shared parent groups to both sidebar layouts. Preserve Classic row
actions and active-child visibility.
- Keep unread state personal to each task. Folding and paging do not
mark tasks read. Counts include readable children beyond ten.
- Target live refreshes with authorized current and previous parent IDs.
Reuse parent metadata from the narrow run-binding read. Resolve fallback
lookups once per delivery batch. Keep the previous summary fallback for
older servers.
- Limit child requests to three at a time. Cancel active and queued
reads when groups leave the viewport.
- Discard extra cached pages on Show less and collapse.
- Compute exact navigation counts in one SQL statement. Materialize
readable candidate IDs once. Use indexed participation sources and
conservative unread candidates before the shared inbox rule.
- Skip recursive privacy walks for standalone open tasks without a
project. Keep the recursive rule for all restricted or inherited shapes
and all delegated principals.
- Add request-count, cancellation, reparenting, read-receipt,
inbox-parity and privacy regressions. Include a disposable PostgreSQL
benchmark.
- Update product and API documentation. Retain the production Storybook
states.

## Verification

- Published head: `4148861437c1b6b635479ad92509dbc71155a232`. Its tree
matches local `04be9d66d481d9bcd1c4d6158acf063a1e65ac7e`:
`a23533e93d3d155918f0254d296a7fd2f0c7c12f`.
- Rebased on master `ca23330c69b1f2b25bdadfcbda68317db97deaef`. Remote
publication preserves prior feature commits.
- The request regression failed before the fix and passes after it. An
unrelated event now sends zero child requests. Current servers also
avoid the unrelated summary request. Old-server events keep one summary
fallback.
- A relevant update after Show less reads one page. Reparenting
refreshes two affected groups. Offscreen reads stay at zero and resume
once on return. Active and queued cancellation tests pass.
- The same synthetic authenticated HTTP workload with 50,000 read
children improved from 767 ms to 92.84 ms median. Five warm samples per
case. The all-unread case improved from 463.85 to 351.65 ms. Untouched
children improved from 208.01 to 131.09 ms. The old-receipt case
improved from 799.70 to 245.80 ms. These local measurements are not a
production capacity guarantee.
- Focused PostgreSQL routes, inbox-parity, privacy and WebSocket tests
passed: 38 tests.
- All 325 affected UI tests passed. All 38 focused PostgreSQL, privacy
and WebSocket tests passed. UI typecheck and low-memory server
declaration checks passed.
- All 41 Chromium Storybook checks passed. They cover 20 states in both
themes and keyboard, folding, paging and unread behavior. They use
production components with HTTP fixtures.
- Both new review findings failed as regressions before their fixes and
pass afterward. Explicit child reads include waiting external
conversations. Deleting a child publishes a separate parent-authorized
update without deleted-child content. Both review threads are resolved.
- `pnpm verify --explain` returned exit 2 because product documentation
requires broader CI. [The prior CI
run](https://github.com/paperclipai/paperclip/actions/runs/43711489306)
found type errors in the new test fixtures. The same errors failed
locally. The fixture fix passes `node
server/scripts/typecheck-layers.mjs --layer test-tree-0` and all 21
issue summary route tests. Production code is unchanged. That CI run
then found a live-delivery read regression. The existing test failed
locally with eight statements against its six-statement budget. A new
PostgreSQL regression also found three parent lookups for two same-batch
calls. Run delivery now reuses parent metadata from its narrow
run-binding query. Fallback lookups resolve to one promise. Both
regressions pass without increasing the budgets. All 74 targeted route,
WebSocket and privacy tests pass. The affected below, above and
test-tree-0 typecheck layers pass. [CI attempt
2](https://github.com/paperclipai/paperclip/actions/runs/43715541480/attempts/2)
passes on the published head. All 62 check runs are terminal and clean:
57 succeeded, two were neutral and three were skipped. Typecheck, build,
policy, all general and serialized server suites, E2E and the [final
verify
gate](https://github.com/paperclipai/paperclip/actions/runs/43715541480/job/132829783231)
pass. The separate security status passes. Attempt 1's server shard 7/12
reached its 20-minute job limit without a test verdict. One retry of
that job passed without a source change. [Greptile completed
successfully on this
head](https://github.com/paperclipai/paperclip/runs/132816163906) with a
[5/5
score](https://github.com/paperclipai/paperclip/pull/21649#issuecomment-6883916606).
All five review threads are resolved. The final CI gate is complete.
- A full local Storybook build exceeded available memory while server
typechecking ran. Browser verification uses the current-source
development server. Rebuilding stale Runner and SDK declarations
resolved the initial server check errors. The first browser attempt
lacked Chromium; all checks passed after installation.
- Reproduce the database measurements with `pnpm --filter
@paperclipai/server exec tsx scripts/benchmark-sidebar-subtasks.ts`.
- Extra local shard diagnosis ran 164 suites. Under this shell's `0077`
creation mask, 157 suites passed and three had fixture permission or
timing failures. Rerunning those three with `0022` resolved the
permission failures. The remaining ten cases passed with one worker: two
workspace cases and eight archive cases. The eight archive cases also
passed on the pre-performance-fix revision, whose archive source is
identical. The broad local shard is not claimed as one passing
execution. The same-head CI retry supplies complete final CI coverage.
- Nothing is merged or deployed.

## Risks

- Exact counts still grow with the readable hierarchy and comment
history. The change reduces repeated work; it does not cap or
approximate counts.
- A relevant summary batch can contain several recent parents. Older
servers retain a broader summary fallback until upgraded.
- Live delivery adds bounded, permission-checked parent lookups. Short
delivery-window reuse limits repeated reads.
- The authorization fast path applies only to open tasks with no privacy
parent and no project. Restricted cases retain the shared predicate.
- No migration is required.

## Model Used

OpenAI Codex, based on GPT-6. Used code execution, native GitHub tools,
PostgreSQL and Chromium verification.

## 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 a public issue or described the issue in this
PR
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal issue
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
- [x] I have considered and documented risks
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open findings
- [x] I will address all review comments before requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-11-15 08:51:04 -06:00
DottaandClaude Opus 5.5 eb65fc0941 fix(server): turn agents' made-up-host Paperclip links into relative routes (#21762)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents post chat replies and task comments that link board pages and
attachments
> - Some models invent a hostname for these links, such as
`https://paperclip.local/COM/agents/<id>` or
`https://paperclip/api/attachments/<id>/content`
> - Those hosts do not exist, so the person clicks a broken link
> - The chat guidance already says never to invent a hostname, but a
model can still do it
> - This pull request rewrites such links to relative app routes before
an agent comment is saved, and adds the rule to the Paperclip skill
> - The benefit is that every board and attachment link an agent writes
opens, on whatever origin the reader uses

## Linked Issues or Issue Description

**What happened?**
Chat-eval cohort 16 (OpenCode with
`openrouter/deepseek/deepseek-v4.1-flash-1017`, master 819f61f1fd). In
`agents.edit-instructions`, the reply linked Morgan as
`[Morgan](https://paperclip.local/COM/agents/<id>)`. In
`onboarding.first-work`, the worker's summary linked its attachments as
`https://paperclip/api/attachments/<id>/content`. Neither host exists.

**Expected behavior**
An agent's link to a Paperclip board or API route opens. Genuine
external links, the instance's own origin, and links inside code stay as
written.

**Steps to reproduce**
Post an agent comment that contains
`[Morgan](https://paperclip.local/<PREFIX>/agents/<id>)`. Before this
change it is stored as written. After it, the stored body links
`/<PREFIX>/agents/<id>`.

## What Changed

- New `server/src/services/agent-invented-host-links.ts`. It rewrites an
absolute link to a relative route only when all of these are true:
- The host is made up: `paperclip`, or `paperclip.<reserved TLD>`
(`local`, `localhost`, `internal`, `test`, `example`, `invalid`, `lan`),
or a loopback host.
- The path is a known board route (`/<PREFIX>/<board root>…`) or, on a
made-up Paperclip host only, `/api/…`.
- A loopback host (`localhost`, `127.x`, `[::1]`) qualifies only for a
board route under the comment's own company prefix. A local app that the
agent built keeps its link, including its `/api` paths.
  - The origin is not this instance's configured public origin.
  - The link is outside fenced and inline code.
- Markdown link targets keep their place. Bare links and autolinks
become Markdown links, so they stay clickable.
- `issueService.addComment` applies it to agent-authored comments,
before the redaction and dedupe steps, so a retried identical comment
still deduplicates. The run-presentation check still compares the text
that the agent wrote. People's comments are not changed.
- `skills/paperclip/SKILL.md` now tells agents to write board and
attachment links as relative paths and never add a hostname.

## Verification

- `pnpm vitest run
server/src/services/agent-invented-host-links.test.ts` (19 tests):
recorded cohort 16 links are rewritten. Negative controls stay
unchanged: external links, a production Paperclip host, the instance's
own origin, local app links, another prefix on localhost, a non-route
path, another single-label host, inline code, a fence, and relative
links.
- `server/src/__tests__/issues-service.test.ts` new case: an agent
comment is stored with the relative route, and a person's identical
comment is stored as written. It fails on master and passes with this
change.
- Per-message cost (local tsx micro-benchmark): the gate on a comment
with no candidate host takes 0.3 µs (500 chars), 1.2 µs (2 KB) and 4.7
µs (8 KB). Only when a candidate exists does it read the company prefix
(one indexed select) and the public origin (config read once per
process), and rewrite (4–40 µs). Nothing runs before a turn starts.
- `server` typecheck passes.

## Risks

- A link on a made-up host to a board route of another company prefix
becomes relative. It opens that route on the reader's instance, where
access checks still apply.
- External channels that cannot resolve relative links already get
relative links from agents today. This change does not alter their
delivery.

## Model Used

- Claude, `claude-opus-5-5` (Claude Code agent 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-15 08:44:06 -06:00
DottaandClaude Opus 5.5 348ed0ae10 fix(runner): keep closing tool-call tags and model control tokens out of OpenCode chat (#21761)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Paperclip Runner OpenCode driver streams model text into the
chat as progress and selects the final reply
> - DeepSeek v4.1 flash (through OpenRouter) wrote tool-call scaffolding
and tokenizer control tokens as ordinary text
> - #21361 hides tool-call markup, but its detector matched only opening
DSML tags, and nothing recognised control tokens
> - A person saw raw `</|DSML| invoke>` lines in a progress message, and
in another conversation got a degenerate reply instead of an answer
> - This pull request extends the same detector to closing DSML tags and
to model control tokens, on the streaming path and at completion
> - The benefit is that scaffolding never reaches the chat, and a
degenerate reply goes to the existing correction instead of being posted

## Linked Issues or Issue Description

Refs #21361

**What happened?**
Chat-eval cohort 16 (OpenCode with
`openrouter/deepseek/deepseek-v4.1-flash-1017`, master 819f61f1fd)
showed two defects.
1. In `task-coordination.block-on-design`, after a real
`paperclip_finish` call, the model streamed a text part that held only
closing tags (`\r\n</|DSML| invoke>\n</|DSML|
calls>…</invoke>\r\n</parameter>`). The driver emitted it as an
`agentMessage` progress delta, so the chat showed raw markup. The cause:
`SENTINEL_FORMS` matched `<|DSML|` but not `</|DSML|`.
2. In `cases.case-history`, the reply to the second follow-up was
`<|begin▁of▁sentence|><?xml version="1.0" …?>\n<output>\nSearch output
truncated. Let me search more specifically…\n</output>`. The driver took
it as the final text part and posted it. The question was never
answered.

**Expected behavior**
Tool-call scaffolding and model control tokens never appear in progress
or in the reply. A reply made only of them goes to the empty-response
correction, which asks the model for the real answer. Real answers,
including answers about XML, chat templates or tool tags, stay as
written.

**Steps to reproduce**
Feed the recorded text parts above to the OpenCode driver (the new
`closing-markup` and `control-token-reply` cases in
`empty-response.test.ts` do this).

## What Changed

- `tool-call-markup.ts`: closing DSML tags (`</|DSML|`, `</|DSML|`)
count as tool-call markup.
- `tool-call-markup.ts`: new `controlTokenStart` finds DeepSeek, ChatML
and Llama control tokens (for example `<|begin▁of▁sentence|>`,
`<|im_start|>`, `<|eot_id|>`) outside code. A new
`visibleBeforeModelScaffolding` holds back both kinds while text
streams.
- Sentinels inside inline code spans are ignored, as fenced code already
was.
- A per-line fast path skips the sentinel scan when a line has no `<|`,
`<|`, `</|` or `</|`.
- `opencode-server-driver.ts`: prose before a control token stays the
answer, with the token removed (for example a trailing end-of-sentence
token). A part with no prose before the token is discarded with the
`opencode_control_token_reply_discarded` diagnostic. The existing
empty-response correction then asks for the answer, with an opening that
names the control tokens. Unlike tool-call markup, this does not make
earlier prose ineligible.

## Verification

- `pnpm vitest run packages/paperclip-runner/src/drivers/opencode/` (20
files, 296 tests pass).
- Red/green: with master's detector and driver, 9 new detector tests and
the `closing-markup` and `control-token-reply` driver cases fail. With
this change they pass.
- The tests use the recorded cohort 16 text. Negative controls: an XML
answer, an answer that names an `<output>` tag, control tokens in inline
code and in a fence, HTML, and comparison operators are left alone. A
driver case checks that `answer.<|end▁of▁sentence|>` keeps the answer
with no correction.
- Per-message cost (local tsx micro-benchmark, 20k calls, one prose line
with `<`): 500 chars 0.3 → 0.8 µs; 2 KB 2.2 → 2.6 µs; 8 KB about 8–16 µs
before and 7–9 µs after (noise range). The detector runs per text-part
update, as before. Nothing runs before the turn starts.
- Paid narrow eval run: results are added in a PR comment.

## Risks

- A real answer that writes a literal control token outside code is cut
at the token. Prose before it stays. That text is never meaningful
prose.
- Closing DSML tags in plain prose (outside code) now hide the rest of
the part. DSML tags are model-internal, so prose does not contain them.

## Model Used

- Claude, `claude-opus-5-5` (Claude Code agent 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>
canary/v2026.1115.0-canary.13
2026-11-15 08:44:00 -06:00
DottaandClaude Opus 5.5 56654adecd perf(server): reuse sandbox provider schemas for five seconds on the remote-run path (#21758)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agent runs can use remote sandboxes that a sandbox provider plugin
supplies (for example Daytona)
> - Each sandbox operation resolves the environment config, and that
step reads the provider config schema to find the secret-ref fields
> - On a hosted instance with 7 remote runs, this schema read was the
most frequent statement: 17.95 per second, about 2.5 per second for each
run
> - The server runs all agents on one Node main thread, so each
statement costs main-thread time; at 1,000 agents this read alone is
about 2,500 statements per second
> - This pull request reuses the retained schema for a short, bounded
time and drops it at once when the plugin registry changes a plugin
manifest
> - The benefit is that a live remote run reads the schema about once
per 5 seconds for each provider, not once per operation

## Linked Issues or Issue Description

**What existing behavior does this improve?**
Every plugin sandbox operation (exec, file sync in/out, runner ingress
attach, capability snapshot, workspace realize, lease resume, lease
release) calls `resolveEnvironmentDriverConfigForRuntime`. That call
runs the `with selected_provider as materialized ...` statement in
`resolvePluginSandboxProviderConfigSchema`, every time.

**Subsystem affected**
Server: plugin environment driver
(`server/src/services/plugin-environment-driver.ts`) and the plugin
registry manifest writes.

**Current behavior**
The schema read runs once per operation. A census test that drives the
real runtime calls of one remote run counts 19 schema reads for 19
operations (see the table below). The hosted measurement was 17.95
executions per second with 7 runs.

**Proposed behavior**
The read runs at most once per 5 seconds for each provider and database
client. A plugin install, upgrade or uninstall through the plugin
registry in the same process takes effect on the next operation.

**Reason and benefit**
The schema is instance-wide plugin manifest data. It does not change
during normal runs. Re-reading it per operation spends main-thread and
database time for no new information.

**Breaking changes**
None. No API, schema or saved-state change.

## What Changed

- `resolvePluginSandboxProviderConfigSchema` now returns the retained
schema without a database read when the entry was checked less than
`PROVIDER_SCHEMA_REUSE_MS` (5,000 ms) ago and the plugin manifest
revision did not change. After that, it uses the existing cheap revision
check, as before.
- A lookup sequence number stops an older, slower lookup from replacing
a newer retained entry.
- A missing provider is still never retained, so a provider that becomes
available is used on the next operation.
- New module `plugin-manifest-revision.ts` holds an in-process manifest
revision counter. It is a separate module so that the registry and the
driver do not import each other.
- `plugin-registry.ts`: `install` (both the new-row and the reinstall
paths), `update` and `uninstall` announce a manifest change after the
write completes. This is 5 changed lines plus 1 import line. Status-only
writes do not announce, because the schema read does not use plugin
status.
- `plugin-loader.ts`: `installPlugin` runs `registry.install` inside an
outer transaction. It now announces the manifest change again after that
transaction settles, so a schema read made before the commit cannot be
reused after it. This is 1 changed line plus 1 import line.
- Statement census per operation, before and after. One remote run, one
secret-ref field in the provider config, embedded test database, fake
in-process plugin worker:

| Operation | Count | Schema reads before | Schema reads after | All
statements before | All statements after |
| --- | --- | --- | --- | --- | --- |
| Lease acquire | 1 | 1 | 1 | 26 | 26 |
| Runner attach (ingress endpoint) | 1 | 2 | 0 | 11 | 9 |
| Capability snapshot | 1 | 1 | 0 | 6 | 5 |
| Exec | 10 | 10 | 0 | 50 | 40 |
| File write (sync in) | 1 | 1 | 0 | 5 | 4 |
| File read (sync out) | 1 | 1 | 0 | 5 | 4 |
| Workspace realize | 1 | 1 | 0 | 5 | 4 |
| Lease resume (reattach) | 1 | 1 | 0 | 6 | 5 |
| Lease release | 1 | 1 | 0 | 18 | 17 |
| **Total** | 18 | **19** | **1** | 132 | 114 |

- Other reads that stay on each operation (reported, not changed in this
pull request): each exec resolves each secret-ref field with 3 reads
(secret, binding, version) and 1 `secret_access_events` insert. Runner
attach and the capability snapshot also read the plugin row by id. These
are part of the secret authorization and audit path, so they keep their
own checks.

## Verification

- `cd server && npx vitest run
src/__tests__/plugin-sandbox-provider-schema-census.test.ts` (new). On
master the census test fails with 19 schema reads. With this change it
passes with 1.
- The new tests also prove these points:
- A registry upgrade that changes the secret-ref fields takes effect on
the next call in the same process.
- A direct manifest change (as from another server process) takes effect
after the 5-second bound, and no read occurs inside the bound.
  - A registry uninstall takes effect at once.
- A plugin reinstall through `pluginLoader.installPlugin` takes effect
after its install transaction commits, even when a schema read ran
inside the uncommitted transaction. This test failed before the
post-commit announcement and passes with it.
- A missing provider is not retained. The next call after install reads
and uses it.
- Two companies share the provider schema but each gets only its own
secret values. A cross-company secret id still fails with "Secret must
belong to same company".
  - A new database client (a process restart) starts cold, as before.
- `cd server && npx vitest run src/__tests__/plugin-database.test.ts`:
passed (plugin install transaction paths).
- `cd server && npx vitest run
src/__tests__/sandbox-provider-schema-reads.test.ts`: the existing tests
now step the clock past the bound where they change the database
directly.
- `cd server && npx vitest run
src/__tests__/environment-runtime.test.ts`: 210 passed.
- `cd server && npx vitest run
src/__tests__/bundled-plugin-registration.test.ts
src/__tests__/external-object-refresh-work.test.ts
src/__tests__/plugin-lifecycle-restart.test.ts
src/__tests__/plugin-loader-error-retry.test.ts
src/__tests__/plugin-environment-driver-sandbox-capabilities.test.ts
src/__tests__/plugin-sandbox-provider-config-validation.test.ts
src/__tests__/environment-probe.test.ts`: 82 passed, 1 skipped.
- `cd server && pnpm typecheck`: passed.

## Risks

- Staleness bound: a plugin manifest change made by a different server
process (for example during an overlapping deploy) can take up to 5
seconds to apply here. During that time, a secret-ref field that an
upgrade adds is not resolved yet, and a field that an upgrade removes is
still resolved. The bound is short and it applies only to which config
paths are secret refs.
- The retained value is instance-wide plugin manifest data, keyed by
database client and driver key. It contains no company data and no
secret values. It does not take part in an authorization decision.
Secret resolution, the environment binding check and the access audit
still run on each operation for the calling company.
- Memory stays bounded by the existing limits: 32 entries per database
client, 64 KiB per schema.
- `plugin-registry.ts` has a small edit in `install`, `update` and
`uninstall`. Other open work in that file can cause a simple merge
conflict.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code 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
- [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

Refs #17581

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 08:09:04 -06:00
DottaandClaude Opus 5.5 15afc32137 test(scaling): wait for agent setup and gate the ramp on a first started run (#21757)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The scaling effort uses a real-agent ramp harness
(`scripts/scale-agents-ramp.ts`, added in #21695) to load a hosted test
instance through the product API
> - Its first real run held a 20-minute step with 10 tasks, 10 queued
runs and 0 started runs, and reported only "concurrency_reached failed
(observed 0)"
> - The cause was in the harness: it bound the agents to a plugin
Runner-task environment, which runs only agents with a managed AI
connection. Each agent stayed in setup (status `paused`, setup state
`verifying`) with that reason, so each run stayed queued. The product
did what it is designed to do
> - The harness did not wait for agent setup, did not read the setup
error, and held the full step with nothing running. Its fake API created
agents ready at once, so its tests could not catch this
> - This pull request makes the harness wait for agent setup, gate the
ramp on one started run, and stop within minutes with Paperclip's own
reason
> - The benefit is that a wrong environment or any other start blocker
costs about one minute and prints the cause, not a 20-minute step with
no explanation

## Linked Issues or Issue Description

Refs #21695

**What happened?**
A ramp of 10 then 50 agents on a hosted test stack created 10 agents, 10
tasks and 10 runs. In 20 minutes no run started. The result said only
"concurrency_reached failed (observed 0)". Cleanup found every agent
already paused and cancelled 10 queued runs. The tasks never left `todo`
(status version 1, no checkout run). The agents were bound to the
"Paperclip Sandbox (Daytona)" plugin environment, whose `daytona-tasks`
driver declares `supportsTasks: true`. For such an environment,
lifecycle verification refuses a `paperclip_runner` agent that has no
`runtimeConfig.aiConnection` (`ai_connection_required`, see
`server/src/services/agent-harness-verification.ts` and its test
"refuses a plugin Runner-task agent without a managed AI connection
before allocating a target"). The failure pauses automatic verification,
so the agents never become ready.

**Expected behavior**
The harness must not create a full step of work before agents can run.
When agents cannot finish setup, or when no run starts, it must stop
soon, print the task, run and agent state with Paperclip's reason, and
clean up.

**Steps to reproduce**
1. Run `node --test scripts/scale-ramp/scale-ramp.test.ts` with the new
fake (agents start in setup; `agentSetupError` keeps them there) and the
old `ramp.ts`, `setup.ts` and `config.ts`.
2. The new test "stops within minutes with Paperclip's reason when the
agents never finish setup" fails with `concurrency_reached`, the same
result as the real run.
3. With this change, it stops with `agents_ready` and the setup reason
in under 5 virtual minutes.

**Paperclip version or commit**
Instance on `2026.1106.0+2555.git.819f61f1f` (master at 11:34Z on
2026-11-15); harness from #21695.

## What Changed

- `setup.ts`: add `waitForAgentsReady`, `agentReady` and
`describeAgent`. The harness reads the company agent list until each
agent has setup state `ready` and is not paused. It stops when an agent
reports a setup error for 60 s, or after `--agent-ready-minutes`
(default 10), and prints the agent's status, setup state, holds and
Paperclip's reason.
- `ramp.ts`: before the first step, a preflight creates one agent and
one task and creates the rest only after that task's run starts. A new
check stops the ramp when no run has started within
`--start-timeout-minutes` (default 5) of the first task. The stop reason
names the task status, any execution blocker, the run status, error
code, error and liveness, and the agent's setup state. New stop
criteria: `agents_ready` and `run_started`. Run records keep `error`,
`errorCode` and `livenessReason`.
- `config.ts`: add `--start-timeout-minutes` and
`--agent-ready-minutes`.
- `fake-paperclip.ts`: agents start as the real product creates them
(status `paused`, setup state `preparing`) and become `ready` after
`agentReadyDelayMs`, or stay in `verifying` with `agentSetupError`.
Issue creation queues a run even for an agent in setup, as the real
product does. Runs start only for a ready agent.
- `scale-ramp.test.ts`: three tests. Agents that never finish setup stop
the run with `agents_ready` and the reason, with one agent and no task
created. A first task that never starts stops the run at the preflight
with `run_started`, the task, run and agent state, and one cancelled
run. The rest of a step is created only after the preflight task starts.
- `doc/plans/2026-11-13-thousand-concurrent-agents.md`: the Phase 3
runbook describes the start checks, the first run's cause, and which
environments the harness can use.

## Verification

- `node --test scripts/scale-ramp/scale-ramp.test.ts`: 43 of 43 pass.
- Red check: with the new fake and tests but the `origin/master`
`ramp.ts`, `setup.ts` and `config.ts`, 3 tests fail. The setup test
fails with `concurrency_reached` (the real run's result) where
`agents_ready` is expected.
- `tsc -p scripts/scale-ramp/tsconfig.json` (same options): no errors.
- Read-only inspection of the hosted instance (GET only): task rows
(`todo`, status version 1, no checkout run), activity (agent created, no
pause, 10 `heartbeat.cancelled` at cleanup), the plugin manifest
(`daytona-tasks` `supportsTasks: true`), and the company AI connections
(no OpenRouter connection). The run and agent rows were deleted with the
agents at cleanup, so their setup error was inferred from the code path
and the cleanup counts, not read.
- Not run: a new real ramp (needs the owner's go-ahead).

## Risks

- Low risk. The change touches only the scale-ramp harness, its fake and
its tests, and one runbook section. No product code changes.
- A real ramp now spends up to one preflight start (seconds to minutes)
before the first step. The preflight task is part of step 1 and the
preflight running samples are dropped, so step metrics keep their
meaning.
- An agent whose setup error clears within 60 s does not stop the run.

## Model Used

Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, read-only HTTP GETs to the test instance).

## 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-15 08:07:03 -06:00
DottaandClaude Opus 5.5 3244780bd0 fix(queue): keep a message a starting run's first turn took out of the queue (#21747)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A message posted while a run is starting goes into that run's first
turn, and the task page shows it as sent
> - The page shows it as sent only while the live queue lists it as a
first-turn message
> - When that queue closes, for example after a later Steer, the page
has no lasting record of the delivery
> - It then infers that the message is queued and shows it again with a
Steer button
> - This pull request reports each run's own first-turn receipt in the
run list, and the page places those messages in that run
> - The benefit is that a sent message stays sent

## Linked Issues or Issue Description

Follow-up to #21661, found while I verified that change on staging.

**What happened?**
With a Codex runner, two messages were posted while the run was
starting. The first turn took them and the agent acted on both. Then a
third message was steered into the running turn. After the Steer, the
first two messages came back into the queue with Steer buttons. The
server queue was empty.

**Expected behavior**
Messages that a run's first turn took stay in the conversation as
delivered.

**Steps to reproduce**
1. Start a task with a Paperclip runner agent.
2. While the runner is starting, post one or two messages.
3. After the turn starts, post another message and click Steer.

## What Changed

- `activityService.runsForIssue` returns `firstTurnCommentIds` from the
run's `firstTurnQueuedInput` receipt. The field is set only when the
receipt names this run, because a retry copies its predecessor's
context.
- `IssueDetail` adds those ids to the run's start inputs, so the
messages are placed in that run and are not inferred as queued.
- `RunForIssue` type gets the new optional field.

## Verification

Red/green tests. Each failed before the fix and passes after it:
- `server/src/__tests__/activity-service.test.ts`: "reports the queued
messages a run's own first turn took, not a predecessor's". 33/33 pass.
- `ui/src/pages/IssueDetail.test.tsx`: "keeps a message the running turn
already took out of the queue after the live queue closes". The
IssueDetail, queue helper, and task-chat suites pass (69 files, 1298
tests). UI typecheck passes.

Staging, after #21661 deployed, Codex runner: two messages posted while
the run started were taken into the first turn and acted on. No
Interrupt, error banner, or composer wait was shown. A mid-turn Steer
was accepted in seconds. This PR fixes the one defect that the check
found.

## Risks

- Low. One new read-only field on the run list. A run that took messages
and then failed before its provider accepted the turn now shows those
messages in that run. The next run still delivers them, and the queue
still lists them while they wait.

## 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
- [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.1115.0-canary.12
2026-11-15 13:05:34 +00:00
DottaandClaude Opus 5.5 e7f31705da perf(release): stage the verified host release daemon instead of compiling it in publish_canary (#21555)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Every master push runs a canary, and only one canary runs at a time,
so its duration sets how often merged work ships
> - `publish_canary` takes about 30 min. 8 min of it is `pnpm build`,
and 4 min 40 s of that is an uncached `cargo build --release` of
`paperclip-runnerd`
> - The release then replaces that binary with the exact-source daemons
that `release_runner_binaries` already built and verified for all four
targets
> - This pull request stages the verified daemon for the publisher's own
target during a release, instead of compiling it
> - The benefit is about 4.5 min less per canary, with the same verified
bytes published

## Linked Issues or Issue Description

**What happened?**
In canary run 43487884481 (2026-11-13), the `Publish canary` step took
28.6 min. Its `pnpm build` ran 19:42-19:50. The
`packages/paperclip-runner build` took 5.3 min, and its `cargo build`
reported `Finished release profile ... in 4m 40s`. Every other package
waited for it. `release.sh` then runs `assemble-daemons`, which
overwrites `dist/bin` with the four exact-source release daemons.

**Expected behavior**
A release does not compile a binary that it discards. The Runner build
stamp stays valid, so the server build still reuses the Runner build.

Refs #21554 (the other canary speed-up)

## What Changed

- `packages/paperclip-runner/scripts/build-runner-binary.mjs` (new):
when `PAPERCLIP_RELEASE_RUNNER_ARTIFACTS_DIR` is set, it checks the
release daemons with the existing `releaseDaemonManifest` (source
revision equal to `HEAD`, digest, architecture, build metadata) and
stages the host target's daemon at `dist/bin` with the existing
`stageRunnerBinary`. Otherwise it runs `pnpm run build:binary` as
before.
- The Runner `build` chain calls this script in place of `pnpm run
build:binary`. `build:binary` itself and the image build are unchanged.
- `stage-release-runner-binaries.mjs` exports `metadataContract`.
- Tests: `stage-runner-binary.test.mjs` (staging per target, wrong
source, bad digest, missing target, non-release fallback);
`runner-image-identity.test.ts` step list.
- `doc/RELEASING.md` describes the behavior.

## Verification

- `node --test
packages/paperclip-runner/scripts/stage-runner-binary.test.mjs`: 9 of 9
pass.
- `server`: `vitest run src/__tests__/runner-image-identity.test.ts`: 42
of 42 pass.
- With the real daemon artifacts of canary run 43487884481 (receipts
pointed at this commit): `PAPERCLIP_RELEASE_RUNNER_ARTIFACTS_DIR=...
pnpm run build` in `packages/paperclip-runner` finished in 15 s with no
`cargo` line. The build stamp was recorded, and
`server/scripts/prepare-runner-vendor.mjs` then reported
`action:reuse,reason:inputs_unchanged`. The staged daemon runs.
- After merge: the next canary's `packages/paperclip-runner build` log
shows "Staged the verified exact-source linux-x64 release daemon" and no
`Compiling` lines.

## Risks

- Low. A release still fails closed: a daemon with the wrong source,
digest, architecture or metadata stops the build, and `assemble-daemons`
checks all four again afterwards.
- Local, Docker and CI builds without the variable are unchanged.
- On macOS, staging re-signs the binary, as it does for a compiled one.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, 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
- [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>
canary/v2026.1115.0-canary.11
2026-11-15 06:40:21 -06:00
DottaandClaude Opus 5.5 8cd2d6a73d docs(skills): add aggregate-bound, lost-runner, and bug-class lessons to fix-failed-paperclip-run (#21745)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The `fix-failed-paperclip-run` skill guides agents that repair
failed or stuck runs
> - A recent repair series made automatic recovery more aggressive, and
three lessons came out of it
> - The aggregate number of automatic run starts was not bounded, so an
outage produced many failing starts
> - CI jobs lost to runner shutdowns and tests broken on master held
merges
> - Review rounds kept finding new instances of one bug class, one at a
time
> - This pull request adds those three lessons to the skill in eight
lines
> - The benefit is fewer repair rounds and safer recovery changes

## Linked Issues or Issue Description

**What happened?**

Recovery repairs bounded attempts per task but not the total number of
automatic run starts across a company. During an outage that total was
large and every start failed. CI jobs lost to runner shutdowns held
merges. Review found one instance of a bug class per round.

**Expected behavior**

The skill tells agents to state the aggregate bound for recovery
changes, to re-run lost CI jobs, and to check a whole bug class after
one instance.

**Steps to reproduce**

1. Read `.agents/skills/fix-failed-paperclip-run/SKILL.md` on master.
2. Observe that none of the three points is covered.

Refs #21443, #21561, #21394.

## What Changed

- Section 4: a repair that makes recovery start more runs states its
worst-case company-wide start rate during an outage and what bounds it.
- Section 6: re-run CI jobs lost to a runner shutdown; re-run an
unrelated failing test once, then check master and tell its owner; after
one instance of a bug class, check every entry point or counter of that
class.

## Verification

- `git diff --check`: no errors.
- Documentation only; no code or tests changed.

## Risks

Low risk. The change adds eight lines of guidance to one skill.

## 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-15 06:11:21 -06:00
DottaandPaperclip c17ef9249d fix(comments): keep saved authorization cards from blocking replies (#21744)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - People use task comments to ask for help with pending requests.
> - Saving a comment also checks whether it replaces any pending
requests.
> - A stored request that fails today's payload schema can abort that
comment write.
> - The connection gateway could write such a request without validating
its generated target.
> - This change validates new authorization cards, reads older custom
identities, and keeps malformed requests from blocking comments.
> - Comments remain available while authorization and review gates
retain their authority.

## Linked Issues or Issue Description

**What happened?**

A connection authorization card can contain a generated custom target
key longer than 120 characters. The gateway writes the card directly.
Later, the interaction reader rejects it. Both the task interaction list
and comment submission then return a validation error. Other malformed
saved requests can also abort a comment write.

**Expected behavior**

People can ask questions on a task while authorization is pending. New
cards meet the shared schema. Older generated identities remain
readable. A malformed request never becomes approval because a person
posted a comment.

**Steps to reproduce**

1. Use a personal connection with a long UID and no grant for the
current user.
2. Invoke a tool. The gateway saves an authorization request with the
long UID in its target key.
3. Open the task or post a comment. Reading the saved payload fails the
key length limit.

Related PR searches found no existing repair for this defect. This is a
focused bug fix, with no roadmap feature overlap.

## What Changed

- Validate generated connection authorization payloads before either
insert or update. Use a stable SHA-256 target identity from the existing
connection/user idempotency key. Bound its display label.
- Read older confirmation custom keys and labels without the new-input
length limits. Preserve their exact identities. Keep target types, URLs,
document revisions, and resolver checks strict. New requests still use
the strict shared schema.
- During current and historical comment supersession, keep an invalid
saved request pending, report its ID and schema locations, and continue
with valid siblings. Database and other unexpected errors still
propagate.
- Keep this behavior in the gateway writer and interaction owner. The
two existing source files exceed 1,000 lines; the additions extend their
existing write/hydration boundaries rather than introduce another
ownership path.

## Verification

- Reproduced the deployed failure through the browser: comment POST and
interaction GET both returned HTTP 400 for `target.key` exceeding 120
characters. The person's draft was restored.
- Ran the new regressions before the repair: four expected failures and
one short-identity control pass. Failures came from real payload parsing
and real PostgreSQL comment writes, not fixture setup.
- After repair, all 257 tests passed in the complete affected suites:
`issue-thread-interactions-service.test.ts`, `tool-gateway.test.ts`, and
`issue-thread-interactions.test.ts`.
- Safety cases cover fresh and reused authorization cards, repeated
missing-grant calls, refusing another user's credentials, two persisted
follow-ups, strict new-input limits, wrong-company resolution, unsafe
URLs, invalid document revisions, malformed question and confirmation
payloads, and valid sibling supersession.
- Local browser acceptance used an isolated, credential-free source
instance on macOS arm64 with embedded PostgreSQL and Chrome. A card
shaped like an older saved long-key authorization request remained
visible. Two comments saved through Send, including a second after
reload. The original comment persisted and the authorization request
remained pending. No model execution was configured.
- Browser acceptance was repeated on final commit
`58b57dfe104b2ab421c7f24c89db4c29fcfda8ec` after rebase. The server
health and ownership check confirmed that exact serving revision. Both
comments persisted and the authorization stayed pending. Both owned
instances were then stopped. All 257 affected tests passed again after
rebase. The final fixture typing correction passed its six affected
PostgreSQL cases. Greptile reviewed final head
`58b57dfe104b2ab421c7f24c89db4c29fcfda8ec` at 5/5, with zero review
threads or open findings. Required CI is green on that head: aggregate
`ci / verify` and `ci / e2e` both passed. The repository CI run is
https://github.com/paperclipai/paperclip/actions/runs/43710675824 . All
55 completed checks passed; four inapplicable checks were skipped. The
non-required Superagent Security Scan remains in progress at 35%, with
no annotations or reported findings. This external scan is still
unverified; it was not retried or marked as passed.
- `git diff --check` and the module boundary check pass. All seven local
server typecheck layers pass on the final fixture revision. An earlier
run found fixture typing errors; those were corrected and rerun
successfully. Full repo tests, release qualification, and deployment
were not run.

## Risks

- Stored custom keys and labels may exceed current input limits. Only
those length limits change for saved confirmation payloads; unsafe links
and invalid document targets still fail validation.
- A malformed request stays pending and still needs repair. It does not
receive consent, disappear, or block a comment. Its read or resolution
can still return a validation error.
- This PR does not deploy the fix or recover a remote task. The original
environment remains affected until rollout.

## Model Used

OpenAI GPT-6-based Codex, with code editing, shell execution, browser
tools, and PostgreSQL-backed tests. The host does not expose a more
specific model version or context size.

## 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
(behavior and limits are recorded in this PR)
- [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-15 06:10:35 -06:00
DottaandClaude Opus 5.5 689d62661d fix(server): wake a delivery task unscoped when it cannot apply settled hints (#21686)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The delivery work coordinator wakes background tasks when a database
work topic settles, and passes the settled scope hints to the task's
`onSettled`
> - The coordinator calls `onSettled(hints)` before `wake()`
> - If `onSettled` throws on a hint that it does not recognise, the task
is not woken. Only a generic listener warning is logged
> - Hints now cross server processes (#21681), so a hint shape from
another server version can arrive during a deploy overlap
> - This pull request makes the coordinator log a warning, apply the
settlement unscoped once, and always wake the task
> - The benefit is that a hint that a task cannot read never makes the
task miss committed work

## Linked Issues or Issue Description

Follow-up to #21681 (merged). This branch is based on master.

**What existing behavior does this improve?**
How the delivery work coordinator handles an `onSettled` callback that
throws.

**Subsystem affected**
`server/src/services/delivery-work-coordinator.ts`.

**Current behavior**
`subscribeDatabaseWork` calls the coordinator listener, which calls
`task.onSettled?.(hints)` and then `wake()`. If `onSettled` throws,
`wake()` does not run. The work-signal publisher catches the error and
logs "Database work listener failed". The task stays asleep until a
different event or deadline wakes it.

**Proposed behavior**
If `onSettled(hints)` throws, the coordinator logs a warning and calls
`onSettled(undefined)` once, which is the unscoped settlement. If that
also throws, it logs a second warning. In all cases it then wakes the
task.

**Reason and benefit**
A settled event means committed work can be ready. A task must never
miss it because a hint could not be applied.

**Breaking changes**
None.

## What Changed

- `delivery-work-coordinator.ts`: a settled event goes through
`applySettled(hints)`. It tries `onSettled(hints)`. If that throws and
hints were given, it tries `onSettled(undefined)` one time. Each failure
logs `Delivery settlement could not be applied for <queue>` with
`process.emitWarning`. Then `wake()` runs.
- Unscoped means `onSettled(undefined)`. Each registered task already
defines what that means. For example, scoped deadline queues, dispatch
work, muse maintenance and the revocation index mark `*` dirty.
Counter-style tasks set their request flag. `chat-action-work` does
nothing. The fallback is bounded: it calls `onSettled` at most twice per
event, it does not recurse, and it does not schedule another settlement.
So it cannot loop.
- `work-signals.test.ts`: a new test pins one rule of #21681 for the
local path and the remote path. An unhinted `signalDatabaseWork` in the
same transaction as a hinted one gives a settlement that is scoped to
the hinted set. The owner of `work-signals.ts` confirmed that this is
deliberate. The repository does not allow code comments in pull
requests, so this sentence and the test document it.

## Verification

- `cd server && npx vitest run
src/__tests__/delivery-work-coordinator.test.ts`: 31 pass. New tests:
- An `onSettled` that throws on an unknown hint shape: the task gets
`[hint]` and then the unscoped settlement, it is woken once, and one
warning is logged. `onError` is not called.
- An `onSettled` that always throws: the task gets 2 calls and is woken
once, with 2 warnings. A later unscoped event gives 1 call, 1 wake and 1
warning. No more runs happen after 60 seconds, so there is no loop.
- A normal `onSettled`: it gets the hints once, the task is woken once,
and no warning is logged.
- Red/green: with the coordinator from master, the 2 throwing tests
fail. `onSettled` is called only with the hints, and there is no
unscoped settlement and no wake. With this branch, all tests pass.
- `cd packages/db && npx vitest run src/work-signals.test.ts -t
alongside`: passes on real PostgreSQL. The local listener and the
receiving process both get `["company-1"]`.

## Risks

- Low risk. The change applies only when `onSettled` throws. Before,
that path skipped the wake. Now it wakes with an unscoped settlement.
For scoped deadline queues an unscoped settlement is a `*` reload. That
is the existing safe fallback, and the reconstruction interval of the
queue still throttles it.
- A task whose `onSettled` throws on every event now runs on every
settled event and logs a warning each time. Before, it did not run. The
warning makes such a defect visible.

> 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 edit, 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
- [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-15 06:02:54 -06:00
DottaandClaude Fable 5.2 fb3b09aaef refactor: split the runner-e2e and restart-chaos READMEs into a runbook and a catalog (#21743)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `tests/runner-e2e` is the paid Product E2E harness and
`tests/restart-chaos` is the restart chaos harness
> - A README is the first file a person or an agent opens in a directory
> - These two READMEs grew to 3,805 and 2,277 lines. Most of each is a
catalog with one section per suite or per fault scenario, and almost
none of it is ever trimmed
> - This pull request splits each README into a runbook and a catalog
file
> - The benefit is a README that can be read in full, and a clear place
for the next suite or scenario note

## Linked Issues or Issue Description

Refs #21670 and #21700 (the same cleanup for `doc/DEVELOPING.md` and
`doc/DATABASE.md`).

**Issue type**

Outdated or confusing documentation.

**Where is the issue?**

`tests/runner-e2e/README.md` and `tests/restart-chaos/README.md`

**What's wrong?**

In the last 60 days, `tests/runner-e2e/README.md` gained 3,476 lines and
lost 182. `tests/restart-chaos/README.md` gained 2,411 and lost 134. The
setup, evidence, and CI sections sit between suite notes. The first 225
lines of the runner-e2e README are suite notes with no heading.

**Suggested fix**

Keep how to run the harness in the README. Move the per-suite and
per-scenario sections to a catalog file in the same directory.

## What Changed

- `tests/runner-e2e/README.md` is now 767 lines: credentials, local
commands, the Daytona image, evidence and cleanup, billing, the
dashboard, GitHub Actions, and the report preview.
- New `tests/runner-e2e/SUITES.md` (3,055 lines) holds every per-suite
section. The two blocks of suite notes that had no heading now have one.
- `tests/restart-chaos/README.md` is now 592 lines: run, fault timing,
Daytona mode, hosted mode, universal checks, grading notes, pieces,
output, and the crash-point suite.
- New `tests/restart-chaos/SCENARIOS.md` (1,694 lines) holds every
workload and fault scenario section.
- All text is moved without wording changes. Nothing is deleted. The
only edits are three "(below)" references in the restart-chaos README,
which are now links.
- Repointed 22 anchor links and 3 plain links in `doc/evals.md` and
`maps/feature-map/cases.md`.
- Updated seven code comments in `tests/restart-chaos/` that name a
moved section, and two skills that list the runner-e2e docs to read.

## Verification

- The split script asserts that each source line is kept or moved
exactly one time, and checks the first line of each range.
- A link check on the four files and on every file that links into them
found 0 missing files and 0 missing anchors.
- `tests/runner-e2e/daytona-image.test.ts` reads the README for a Docker
build recipe. The recipe is still in the README. I did not run that test
locally.
- `node scripts/check-maps.mjs` passes.
- `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail.
- `pnpm verify` was not run. This worktree has no installed
dependencies.

## Risks

- Low risk. The change is documentation and comments only.
- A link to a moved section from outside this repository lands on the
top of the README.
- The catalog files are still long. This change moves them off the
first-read path. It does not prune them.

## Model Used

- Claude Fable 5.2 (`claude-fable-5-2`), Claude Code desktop, 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
- [ ] 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-15 06:01:06 -06:00
DottaandClaude Opus 5.5 066c8244b5 perf(release): build canary daemons during source verification and keep their dependency cache (#21554)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Every master push runs a canary that publishes npm packages and
reaches staging
> - Only one canary runs at a time, so a canary's duration sets how
often merged work ships
> - A canary takes about 70 min. Two parts of it are avoidable waiting:
the Runner daemons build only after the source proof, and darwin-x64
often rebuilds every dependency crate
> - This pull request starts the daemon builds with the canary and keeps
their dependency cache across Runner changes
> - The benefit is about 15-25 min less per canary, with no change to
what must pass before publication

## Linked Issues or Issue Description

**What happened?**
In successful canaries on 2026-11-13 the critical path was: `Reuse
exact-source verification` 11-14 min, then `Release daemon (darwin-x64)`
10-28 min (9 runs: 10, 16, 18, 20, 20, 21, 24, 24, 28), then
`publish_canary` 27-37 min. The daemon builds waited for the source
proof, although they only build and upload artifacts. The darwin-x64
build was 16.4 min with a cache miss and 3.9 min with a hit. The native
cache key included a hash of `packages/paperclip-runner/src/**`,
`protocol/**` and `*.json`, but the cache holds dependency crates only
(`cache-workspace-crates: false`). So every Runner change caused a full
dependency rebuild.

**Expected behavior**
Daemons build in parallel with the source wait. The dependency cache
changes only when dependencies, Cargo configuration, host or target
change.

Refs #21399, #16028

## What Changed

- `release.yml`: `release_runner_source` no longer needs
`verify_canary`. On a canonical master push it starts at once.
`publish_canary` still requires `verify_canary.result == 'success'`, so
nothing publishes from unverified source.
- `release-verify.yml`: the native Rust cache `shared-key` drops the
Runner source hash. It keeps the Cargo manifest and configuration, host
and target.
- `release-verify-workflow.test.mjs`: tests that a canonical master push
selects the source without the proof, that a fork, other ref or other
event does not, that `publish_canary` still needs the proof, and that
the cache key contains no source globs.
- `doc/RELEASING.md`: describes both behaviors.

## Verification

- `node --test scripts/__tests__/release-verify-workflow.test.mjs`: 73
of 73 pass.
- Red: the same tests against master's `release.yml` and
`release-verify.yml` fail 2 tests (the source selection and the cache
key).
- After merge: the next canary shows `Release daemon (*)` starting at
the same time as `Reuse exact-source verification`, and darwin-x64
restores its cache.

## Risks

- Low. If verification fails, that commit's daemon builds are wasted
macOS minutes. Verification failures on master are now rare.
- The first canary after merge saves a new cache entry, so it is not
faster for darwin-x64. Later canaries are.
- Stable, beta and nightly still select their source through their own
gates, unchanged.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, 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
- [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-15 05:57:44 -06:00
DottaandClaude Opus 5.5 83541e89ad perf(recovery): re-check only changed tasks between hourly full backstop passes (#21729)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The server runs issue recovery queues on one Node main thread.
`stranded-assignments` and `assigned-work-invariant` find assigned tasks
that have no live run and restart them.
> - #21552 scoped run hints to the run's task graph and kept a company
"backstop" pass to catch a missed hint. Any graph hint arms the
backstop, and the backstop runs at most every 5 minutes after the last
full pass.
> - The backstop reloads and re-checks every open assigned task of the
company. With any trickle of activity it runs every 5 minutes. On the
hosted staging instance that is about 850 tasks every 5 minutes, about
2.8 checks per second at idle, close to the measured 3.2 per second.
That is work proportional to history, not to activity.
> - This pull request makes the 5-minute backstop re-check only tasks
whose own rows changed since the previous look, with one set-based
query. A full company pass runs at most once an hour, still armed only
by activity.
> - The benefit is no re-checks between hourly passes when nothing
changed: idle statements drop from 59 per second to 5.5 per second in a
staging-shaped fixture. A task whose own state changed without a hint is
still recovered within 5 minutes.

## Linked Issues or Issue Description

No issue exists. This describes the problem with the fields of
`.github/ISSUE_TEMPLATE/enhancement.yml`.

**What existing behavior does this improve?**

The missed-hint backstop of the `stranded-assignments` and
`assigned-work-invariant` recovery queues
(`server/src/services/recovery/work.ts`).

**Subsystem affected**

Server: issue recovery background work.

**Current behavior**

Each graph hint arms a `{companyId, backstop: true}` scope. When it
opens (5 minutes after the last full pass), the queue loads every open
assigned task of the company and checks each one again: about 22
statements per task for the stranded check. With a hint at least every 5
minutes, this repeats every 5 minutes, whatever changed.

**Proposed behavior**

Between full passes, the backstop loads only the tasks whose own rows
changed since the previous look (minus a 5-minute overlap for late
commits): the task row, its runs, its recovery actions, its wake
requests, its thread interactions, its comments, or its assignee agent.
A full company pass runs when the last one is an hour old. A real change
still sends its own hint and gets an immediate targeted check.

**Reason and benefit**

On staging at idle, the stranded check runs about 3.2 times per second
with zero runs. A fixture with staging's population shape attributes all
of it to the backstop.

## What Changed

- `server/src/services/recovery/work.ts`:
- `fullPasses()` keeps the time of the last full pass and of the last
changed-tasks pass per company. The backstop gate is 5 minutes after the
later of the two.
- A backstop scan decides on its first page: a full load when the last
full pass is at least `ISSUE_RECOVERY_FULL_BACKSTOP_MS` (1 hour) old,
otherwise a changed-tasks load since the previous look minus
`ISSUE_RECOVERY_BACKSTOP_MS`. All pages of one scan use the same
decision.
- Each scan records its start time on its first page. A completed scan
advances the saved full or changed time only to that start, so a change
behind the cursor of a slow scan falls in the next window.
- The stranded queue adds `changedTaskCondition(since)` to its load
query. The assigned-work queue passes `changedSince` to `listSuspects`.
Both return `keepUnseen: true` for a changed-tasks load.
- A new `fullBackstopMs` option. When a caller sets only `backstopMs`
(tests), every backstop stays a full pass, as before.
- With `PAPERCLIP_DEBUG_WORK_SIGNALS=stranded-assignments`, each `check`
event now names why the task was loaded: `deadline`, `reload` (unscoped
reconstruction), `backstop`, `company` (company-wide hint) or `hint`
(task or graph hint).
- `server/src/services/recovery/changed-tasks.ts` (new): the set-based
"changed since" condition. Each part uses an existing index: `issues
(company_id, updated_at)`, runs by `(company_id, context issueId)`,
wakes by `(company_id, payload issueId)`, interactions and comments by
`(company_id, issue_id)`.
- `server/src/services/scoped-deadline-work.ts`: a load result may set
`keepUnseen`. Then a completed scan does not drop the pending entries it
did not load, so their saved deadlines stay.
- `server/src/services/recovery/assigned-work-sweep.ts`: `listSuspects`
accepts `changedSince`.
- `server/src/services/issue-recovery-notifications.ts`:
`ISSUE_RECOVERY_FULL_BACKSTOP_MS = 60 * 60_000`.
- Tests:
- `server/src/__tests__/issue-recovery-idle-backstop.test.ts` (new): the
staging-shaped fixture, see Verification.
- The staging-shaped population helper and the fixture's statement meter
come from #21724, now merged into this branch.
- `server/src/__tests__/issue-recovery-work-debug-attribution.test.ts`:
the check event now names its load reason (`hint` or, when the backstop
loaded the task last, `backstop`) instead of `load`.
- `server/src/__tests__/issue-recovery-deadlines.test.ts`: the backlog
helper writes its rows with the test's fake clock, as production writes
use the server clock. Without it, rows stamped with the database clock
look older than the fake-clock window.

## Verification

- Fixture (`issue-recovery-idle-backstop.test.ts`, embedded PostgreSQL,
the real recovery, dispatch and retry-cancellation workers, fake clock,
statement meter, `PAPERCLIP_DEBUG_WORK_SIGNALS=stranded-assignments:1`):
one company, 50 agents, 780 in-review tasks with succeeded native runs
and no execution state, 40 in-progress and 30 to-do tasks of a paused
agent, 12 tasks with an active agent-owned recovery action, 3 tasks of a
terminated agent. After boot, one unrelated graph hint per minute stands
in for idle activity.
- Wake reasons on master over 30 idle minutes with that trickle: 5,100
stranded checks, all `backstop`; 0 from hints, 0 from company hints, 0
from deadlines. That is 2.83 checks per second and 106,632 statements
(59.2 per second). With no hint at all after boot, master still made one
backstop pass (850 checks) in 30 minutes, armed by boot activity.
- This branch, same fixture:

  | | master | this branch |
  | --- | --- | --- |
  | Stranded checks, first 30 idle minutes | 5,100 | 0 |
  | Statements, first 30 idle minutes | 106,632 | 1,044 |
| Stranded checks, one idle hour (one full pass) | about 10,200 | 850 |
  | Statements per second over that hour | 59.2 | 5.5 |

- Missed hint: a task inserted with no hint is checked and gets a run
within 5 minutes plus one pass (`ISSUE_RECOVERY_BACKSTOP_MS + 2 min`
asserted).
- A change outside the task's own rows (its agent resumed by a raw
update that sets no `updated_at`, with no hint) is not seen by the
5-minute pass. It is checked and gets a run after more than 10 minutes
and within 62 minutes, through the hourly full pass.
- Prompt pickup with the backstop closed: a finished run
(`notifyNativeStatusReassessment`), a user comment, a hold release
(`pause_lifted`, which a budget raise and an agent resume send) and an
agent resume each get a check of the affected task within 60 seconds.
The company-wide events re-check the whole company at 25 tasks per pass,
as before.
- Two regression tests in `issue-recovery-deadlines.test.ts`, red on
379dda9e26 and green on 802a76c153:
- "keeps a saved deadline of a task that a changed-tasks backstop pass
does not load": a task with a 16-minute saved deadline is checked at
that deadline after two changed-tasks passes that did not load it.
- "starts the next changed-tasks window from the start of a slow
backstop scan": each check advances the clock by 20 s, so the scan spans
more than 10 minutes. A task changed behind the cursor early in the scan
is read by the next changed-tasks pass.
- #21552 backstop tests in `issue-recovery-deadlines.test.ts` pass,
including "finds a stranded task outside the affected set within the
backstop bound", which now runs with the production defaults.
- Regression, embedded PostgreSQL: issue-recovery-idle-backstop,
issue-recovery-deadlines, scoped-deadline-work,
assigned-work-recheck-idle, live-recovery-work (98 tests; "resolves a
run's task graph through index lookups" failed once under 3 parallel
workers and passes alone; it does not touch this change);
live-recovery-work, assigned-work-recheck-idle, assigned-work-invariant,
recovery-deadline-acceptance, issue-recovery-recorded-decision-idle,
continuation-delivery-unwakeable-agent-idle.
- `tsc --noEmit -p server/tsconfig.json` passes.

## Risks

- **The missed-hint bound changes for one class of change. The owner
must see this.** A change that touches the task's own rows (task, runs,
recovery actions, wakes, interactions, comments, or the assignee agent's
row) and sends no hint is still recovered within 5 minutes plus one
pass. A change elsewhere that sends no hint (company or budget rows,
tree holds, an execution-state participant agent, or a write that does
not set `updated_at`) is now recovered within 60 minutes plus one pass,
where it was 5 minutes. Every such writer that I found sends a company
or graph hint, which still triggers an immediate check.
- The changed-tasks window trusts `updated_at` stamps. A transaction
that commits more than 5 minutes after its stamp can be missed until the
next full pass.
- The fixture cannot run the full set of workers that `index.ts`
registers. It runs the recovery, dispatch and retry-cancellation
workers, and stands in for other activity with one graph hint per
minute.
- Not changed here: a company-wide hint (`{companyId}` with no task)
still reloads and re-checks every task, at most every 30 seconds. About
20 writers publish one, for example `documents.ts`, `task-watchdogs.ts`,
`issue-tree-control.ts`, `issues.ts`, `heartbeat/queue.ts` and
`run-dispatch-notifications.ts` without an issue. In the fixture these
came only from boot escalations, not at idle.
- At boot, a graph hint that arrives before the first full
reconstruction completes still opens one full backstop pass.
- master (with #21724) is merged into this branch. The changed-tasks
backstop and #21724's `beforeChecks` pass with its shared review-wait
read work together: the focused tests of both pull requests pass on the
merged tree (107 tests). On the merged tree the hour that holds the full
pass reads 7.7 MB instead of 15.0 MB, because of #21724's lean reads.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file edits, local PostgreSQL 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-15 05:50:59 -06:00
DottaandClaude Opus 5.5 07d5a6ee17 perf(db): carry scope hints in cross-process work notifications (#21681)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Server processes share durable queues and wake each other with a
commit-bound PostgreSQL NOTIFY
> - The NOTIFY payload carries only `{version, origin, topic}`, so the
receiver gets an unscoped "settled" event
> - In `scoped-deadline-work.ts` an unscoped settle becomes `*`, which
reloads every candidate of that queue on the whole instance
> - On a large instance one cross-process notification can re-check
about 850 open tasks, at about 22 statements each
> - This blocks more than one server process per stack, and it costs
work during every deploy overlap
> - This pull request puts the topic's hints in the NOTIFY payload, so
the receiver reloads only the hinted scopes
> - The benefit is that a scoped commit in one process costs the same
scoped reload in every other process

## Linked Issues or Issue Description

**What existing behavior does this improve?**
Cross-process work notifications between server processes on one
database.

**Subsystem affected**
`packages/db` work signals (`work-signals.ts`) and their consumers, such
as `server/src/services/scoped-deadline-work.ts`.

**Current behavior**
`receiveDatabaseWorkNotification` publishes "settled" with no hints. A
scoped deadline queue then reloads all of its candidates, throttled only
by its reconstruction interval.

**Proposed behavior**
The NOTIFY payload carries the deduplicated hints of its topic. The
receiving process publishes "settled" with the same hints that a local
commit publishes. Overflow and malformed input fall back to the old
unscoped behavior.

**Reason and benefit**
A scoped commit no longer causes an instance-wide reload in other
processes. This is necessary before a stack runs more than one server
process.

**Breaking changes**
None. Old and new processes interoperate in both directions (see Risks).

## What Changed

- `packages/db/src/work-signals.ts`: the per-level pending notifications
are now a map of topic to `{ hints, unscoped }`. Savepoint merge and
rollback keep the same rules as before.
- The hints follow the local "settled" semantics: the union of the hints
from `signalDatabaseWork` and `publishDatabaseWorkSettled`. An unhinted
`publishDatabaseWorkSettled`, `notifyDatabaseWorkOnCommit`, or a topic
with no hints sends the unscoped payload.
- A hinted payload is `{version: 1, origin, topic, hints: [...]}`. The
field is additive and the version stays 1.
- Each payload is at most 1,024 bytes
(`DATABASE_WORK_NOTIFICATION_MAX_BYTES`), because current receivers drop
any payload longer than 1,024 characters before they parse it. Many
hints split into several payloads. The payloads of one topic are at most
7,000 bytes in total (`DATABASE_WORK_TOPIC_NOTIFICATIONS_MAX_BYTES`). If
a topic exceeds this cap, or one hint alone does not fit, the topic
sends one unscoped payload.
- All payloads still go in the one batched `select pg_notify(...) from
jsonb_array_elements_text(...)` statement at commit. There are no added
statements or awaits on the commit path.
- `receiveDatabaseWorkNotification` accepts payloads up to 8,000
characters (the PostgreSQL limit). It keeps the drop of own-origin
payloads and of payloads without a usable origin or topic. A missing,
malformed, or empty hint list, or a version other than 1, gives an
unscoped wake. It never throws.
- The `remote_notification` debug event now logs the received hints
(`hints`: a JSON array, or `null` when unscoped).
- Tests: new payload, compatibility and fallback tests in
`packages/db/src/work-signals.test.ts`, and a new two-process test on
real PostgreSQL in
`server/src/__tests__/scoped-deadline-work-notifications.test.ts`.

## Verification

- `cd server && npx vitest run
src/__tests__/scoped-deadline-work-notifications.test.ts`: two pools on
one embedded PostgreSQL database. Process A commits work. Process B runs
a real delivery coordinator with `registerScopedDeadlineWork` over 800
candidate rows in 20 companies.
- Master (red): a commit hinted with one company makes B load `*`: 1
load, 801 rows.
- This branch (green): B loads only `company-7`: 1 load, 41 rows. A
commit with two hints loads only those two companies (80 rows). An
unscoped commit still loads all 801 rows.
- `cd packages/db && npx vitest run src/work-signals.test.ts` (32 tests,
real PostgreSQL). New tests:
- deduplicated hints per topic, including a released savepoint and a
rolled-back savepoint
- split into payloads of at most 1,024 bytes, at most 7,000 bytes in
total, and the union of hints is complete
  - overflow and one oversized hint fall back to one unscoped payload
- malformed hint lists and unknown versions wake unscoped; unusable
payloads do not wake; own-origin payloads are dropped; nothing throws
- an old-format payload `{version, origin, topic}` gives an unscoped
wake
- every new payload passes a copy of the receiver from master, which
reads it as an unscoped wake for the correct topic
  - the debug event logs the received hints
- With master's `work-signals.ts`, 5 of these tests fail (red). With
this branch, all pass.
- Also run: `scoped-deadline-work.test.ts`,
`delivery-work-coordinator.test.ts`, `deployment-notifications.test.ts`,
`run-start-handover.test.ts`, `heartbeat-run-start-handover.test.ts`,
`heartbeat-run-event-atomic-append.test.ts` (111 tests pass),
`work-signal-debug.test.ts` (12 pass), and `tsc --noEmit` for
`packages/db`.

## Risks

- Mixed deploys, new sender to old receiver: every payload is version 1
and at most 1,024 bytes. The old receiver ignores the `hints` field and
wakes unscoped, as today. A commit with many hints sends several
payloads, so an old receiver can get up to about 7 unscoped wakes for
one commit. The coordinator merges them into one `*` reload.
- The sender bounds bytes, and old receivers compare `.length` in UTF-16
code units. A string never has more UTF-16 code units than UTF-8 bytes,
so a payload of at most 1,024 bytes always passes the old check.
- PostgreSQL collapses identical NOTIFY payloads in one transaction. The
chunks of one topic always carry different hints, so PostgreSQL drops
none of them.
- Mixed deploys, old sender to new receiver: the old payload has no
`hints`, so the new receiver wakes unscoped, as today.
- I did not use one large payload of about 7 KB: current receivers drop
any payload over 1,024 characters before they parse it, so they would
miss the wake during a deploy overlap.
- Consumers that read hints (for example `chat-action-work`,
`approval-queue-seeding-work`) now get the same hints from another
process that they already get from a local commit. Before, they got no
hints from another process.
- The receiver accepts hint strings from the database channel. Consumers
decode them in the same way as local hints. `scoped-deadline-work`
already turns a decode failure into a `*` retry.

> 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 edit, 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
- [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-15 05:38:06 -06:00
DottaandClaude Opus 5.5 819f61f1fd fix(evals): repair four cohort-15 chat cases and prefix board links in completion feedback (#21682)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The chat-feature eval catalog runs real chat journeys. It grades
saved state, rendered links and run ledgers.
> - Chat-eval cohort 15 (OpenCode with
`openrouter/deepseek/deepseek-v4.1-flash-1017`, master `36101ebcb9`)
failed four cases where the agent did the right thing or where our own
server text misled it.
> - One failure was a harness race introduced by #21667. Two failures
came from graders that read free-form text with keyword regexes. One
failure came from an unprefixed approval link in the server's completion
feedback, plus a grader that required a literal prefix.
> - This pull request fixes the harness step, replaces the free-form
graders with saved-state and clicked-link checks, and makes the server
emit company-prefixed board links.
> - The benefit is that these cases measure the feature again. The
retained correct outcomes pass, and the relevant broken outcomes still
fail.

## Linked Issues or Issue Description

Refs #21667

**What happened?**
In chat-eval cohort 15, four cases failed:
- `projects.share-project`: the harness followed the agent's ID-based
project link. The app then rewrote the URL to the project slug and
redrew the page. The owner step timed out because Riley's option in the
people picker was "detached from the DOM". #21667 introduced this path.
- `skills.author-skill`: the saved skill was a correct, richer
checklist. Per-sentence keyword regexes rejected it. For example,
"ignore the mouse" tripped the forbidden word "ignore".
- `inbox-search.show-decisions`: the reply linked the right approval and
tasks and said the question was "addressed to a different teammate". A
regex required the word "Riley".
- `agents.hire-needs-approval`: both replies linked `/approvals/<id>`
without the company prefix. The agent copied that link from
`server/src/services/native-runtime/native-completion-feedback.ts`. The
grader required a literal `/<prefix>/approvals/<id>`, although the board
redirects the unprefixed route.

**Expected behavior**
Correct agent behaviour passes. Grading uses saved state, setup literals
and rendered or clicked links, not free-form wording. The server gives
agents canonical company-prefixed board links.

**Steps to reproduce**
1. Use the retained cohort-15 evidence for the four cases.
2. Run the old graders on the retained skill markdown and decisions
reply. Both fail.
3. For share-project, open a project configuration page by ID while the
app rewrites the route after a delay, then use the access picker before
the rewrite completes.
4. For hire-needs-approval, finish a task with a pending linked
approval. The feedback links `/approvals/<id>`.

**Paperclip version or commit**
master `36101ebcb9` (cohort 15); fixed on top of current master.

## What Changed

- `projects.share-project` (`internal-privacy.ts`,
`runtime-support.ts`): after the harness follows the agent's link, it
waits until the URL settles on the project's canonical route key. This
reuses the #21667 approach for agent profiles: `settleAgentProfileRoute`
now calls a shared `settleRouteKey`, and `projectRouteKey` follows the
app's `projectRouteRef`. The owner's picker selection
(`addProjectAccessMember`) now retries as one unit. If the dialog or
picker closes, or an option detaches, it reopens them, searches again
and selects again. It continues only when the picker shows the person
and Add is enabled.
- `skills.author-skill` (`integrator-skills.ts`): removed the
keyword-regex checklist grader, the waiver regexes, and the reply
regexes for "global activation" and "attached to me" claims. The
saved-state checks stay: one agent-created writable skill, its current
revision authored by the responding agent, the same bytes on the skill
and the revision, the Skills/Studio inspection with reload, and
assignment scope from saved assignments and audit rows. The checklist
check now requires the setup literals `375`, `WCAG` and `AA` as whole
tokens in the saved SKILL.md and in the rendered editor. Whether the
skill still asks for keyboard-only navigation and visible labels, and
whether it waives a check, is left to human review. Oracle version
`skill-authoring.v10`.
- `inbox-search.show-decisions` (`internal-decision-search.ts`): removed
all reply regexes, including the `Riley` requirement and the
wording-based separation checks. The grade now uses saved state (pending
decisions unchanged, answered history unchanged, each person's own
attention queue and resolver) and rendered links to the exact approval,
the question's task and the history task. Oracle version
`decision-search.v3`.
- Product (`native-completion-feedback.ts`): the completion feedback now
links `/<prefix>/approvals/<id>` and `/<prefix>/issues/<identifier>`.
This fixes the approval link and the four sibling task links in the same
file.
- `agents.hire-needs-approval` (`runtime-hiring.ts`): the harness now
clicks each reply's rendered link to its approval and records where the
UI lands. The grade accepts a prefixed link, or an unprefixed link that
the board redirect lands on `/<prefix>/approvals/<id>` with the proposed
hire visible. Without such a link, the harness still opens the approval
directly so later phases keep their evidence, and the grade fails.
Oracle version `runtime-hiring.v4`.
- No eval YAML changed, so the TestOps manifest does not change.
`chat-catalog-descriptors.json` records the three oracle version bumps.

## Verification

- Red/green tests (each new test fails on the old code and passes on the
new code):
- `internal-privacy-share-route.test.ts` (real Chromium): the project
page rewrites its route after 0, 400 and 1500 ms, and one case closes
the picker while its first results render. With the old flow, the 400 ms
rewrite and the closed picker both time out on the option click (the
cohort-15 failure). With the fix, Riley is added on the settled route in
all cases.
- `integrator-skills.test.ts`: the retained cohort-15 SKILL.md passes.
The old grader rejects it. A stale skill body, another author, and a
lost 375 width still fail.
- `internal-decision-search.test.ts`: the retained cohort-15 reply and a
reworded reply pass. The old grader rejects the retained reply. A
missing or wrong approval, question-task or history-task link fails.
- `native-completion-feedback.test.ts`: a pending linked approval
produces `[the pending approval](/<prefix>/approvals/<id>)`, and a
pending review stage produces a prefixed task link. The old code
produces `/approvals/<id>`.
- `runtime-hiring.test.ts`: unprefixed links that the redirect lands on
the right approval pass. The old grader rejects them. A link that did
not land, landed on another approval, was not clicked, or is another
href still fails.
- `npx vitest run --config tests/runner-e2e/vitest.config.ts
chat-catalog`: all passed (one negative control in `internal.test.ts`
changed from a reply wording to "approved while listing").
- `pnpm test:e2e:runner:typecheck` and `server` `tsc --noEmit`: passed.
- `server` vitest for `native-completion-feedback`,
`native-current-wake-completion-feedback` and
`heartbeat/run-completion`: 201 tests passed.
- Narrow paid run of the four full case ids on this branch: run
43657390762 (results are added in a comment).

## Risks

- Low risk. The product change only adds the company prefix to links in
agent feedback text. It adds one indexed company read, and only on the
branches that return a link.
- Less is graded automatically, by design. `skills.author-skill` no
longer checks that the skill keeps the keyboard-only and visible-label
checks or that it does not waive a check. `inbox-search.show-decisions`
no longer checks how the reply names resolvers or separates the person's
decision from others' and from history. `skills.author-skill` no longer
checks whether the reply describes the assignment scope truthfully. A
person reviews this meaning. Saved state and links still catch the
plausible broken outcomes listed above.
- `agents.hire-needs-approval` now needs a reply link that really opens
the approval. A reply without a link to its approval fails as before.

## Model Used

- Claude, model ID `claude-opus-5-5` (Claude Code agent 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-15 05:34:56 -06:00
DottaandClaude Opus 5.5 ca23330c69 fix(recovery): continue a task on its own when its saved files are permanently lost (#21541)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - When a run stops early, Paperclip recovers its saved files and then
continues the task automatically
> - Sometimes the sandbox is gone. Then saved-work recovery ends with
`source_unavailable` (use another strategy)
> - In that state the task showed Retry. Retry worked, because it
continues in a fresh workspace. But nothing continued the task
automatically
> - A task must never need a person's Retry for a system failure. The
target is 0%
> - This pull request lets the system take the same fresh-workspace step
that Retry takes, when the saved files are permanently lost
> - The benefit is that these tasks continue on their own, and the sweep
reports them correctly

## Linked Issues or Issue Description

Refs #21478

**What happened?**
A legacy run on a remote sandbox failed in setup. Its unsaved files were
held for saved-work recovery. The sandbox was gone, so the recovery
ended `source_unavailable` / `use_alternative_strategy`. The task then
showed Retry. For about 2 hours, the assigned-work sweep logged
`retry_offered` with outcome `not_started` every 15 minutes. A person
had to press Retry.

**Root cause**
The fresh-continuation fallback returned `person_owned` /
`retry_needed`. It does this when a later run of the task was withheld
at dispatch (here, a scheduled retry that the hold blocked) and the
source run does not continue automatically. The source was a person's
earlier Retry that failed with `setup_failed`, so it was not an
automatic recovery run and not a restart-class failure. Without the
withheld run, the same task already continued automatically.
Restore-hold ownership (`isOwnedReconciliationHold`) and the legacy
refusal in `inspectFallback` were not the blocker.

**Expected behavior**
When saved-work recovery proves that the files are permanently gone, the
system continues the task in a fresh workspace on its own. This is the
same path that Retry takes.

## What Changed

- `fresh-continuation-fallback.ts`: the eligibility rule
(`interruptionEligibility`, which the fallback and the backlog pass
share) also accepts a system-owned source run when a hold of that run
has saved-work recovery `exhausted` with a permanent unverifiable-source
failure (`UNVERIFIABLE_SOURCE_CODES` ×
`PERMANENT_SOURCE_RETRY_CLASSES`).
- `recovery/assigned-work-sweep.ts`: admission can settle the hold and
coalesce the sweep's wake into a pending fresh continuation. The sweep
now reports this as `repaired` / `queued` (`continuedFromSavedWork`).
Before, it reported `enqueue_refused` / `not_started`.
- `legacy-execution-recovery.ts`: the stranded sweep calls
`terminalizeLegacyExecution` for the same failed run on every pass. Its
restore-hold branch rewrote the hold every time, with a new
`automaticRecovery.recordedAt`, a new `updatedAt`, and
`continuationDelivery: "invalidated"`. The branch now returns early when
the hold already records the same no-replay decision for this run, or
when a fresh continuation took the hold over. Finding: a continuation
that was already recorded was not clobbered, because the existing
`executionReconciliation.runId` guard returned early. But a hold with a
`coalesced` delivery state would have been reset, and the churn kept
bumping `updatedAt`.
- New regression test `legacy-source-unavailable-continuation.test.ts`.
The existing `assigned-work-invariant` test now expects the corrected
sweep outcome.

## Verification

- Red/green: `legacy-source-unavailable-continuation.test.ts` uses
`failedRemotePreparation()` with a `destroyed` termination receipt,
`recoverRetainedWorkspace`, a withheld scheduled retry, and a source
that was a person's Retry. Then it runs
`assignedWorkSweep(...).checkIssue` with the real
`heartbeatService(db).wakeup`.
- Without the fix: outcome `enqueue_refused`, and the fallback returns
`person_owned` / `retry_needed`.
- With the fix: outcome `repaired`. A stranded pass keeps
`continuationDelivery: "pending"`. `deliverReconciledExecutions` starts
the successor run. The task no longer shows Retry. There is no
`not_started` entry.
- Red/green: the "revisits" test fails without the
`terminalizeLegacyExecution` guard, because the hold evidence changes.
It passes with the guard.
- Locally passing: `fresh-continuation-fallback`,
`fresh-continuation-move-forward-offer`,
`fresh-continuation-retry-delivery`, `legacy-execution-recovery`, both
`assigned-work-invariant` suites, `assigned-work-stalled-queued-run`,
`assigned-work-sweep-round-trips`, `saved-work-recovery-overdue`, and
the new test file (10 files, 225 tests). `tsc --noEmit` passes for
`server`.
- Not run locally: the full suite. CI covers it.

## Risks

- Behavior shift: a task whose source failure is system-owned now
continues automatically after its saved files are proven permanently
gone, even when an earlier wake was withheld. The new run does not
replay the old run. It starts in a fresh workspace, with the same notes
and quarantine that Retry uses. Person-owned failure codes still wait
for a person.
- The new hold guard can skip a rewrite. It skips only when the hold is
already resolved with the same no-replay decision and the same
restore-recovery data. A changed decision is still written; the test
covers this.
- No schema changes.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, local Vitest against embedded Postgres).

## 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.1115.0-canary.10
2026-11-15 05:22:00 -06:00
DottaandClaude Opus 5.5 68f641ba0b fix(recovery): continue a native run cut off by a sandbox client timeout (#21736)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The native runtime runs an agent's provider turn in a sandbox (for
example Daytona) and records each failure on the run and its native
coordinator
> - A Daytona SDK request can hit its client-side deadline during a
provider turn. The run then fails with `native_session_interrupted` in
an ambiguous state, because the turn started and its outcome is unknown
> - That failure blocks the task under a board-owned watchdog hold. No
recovery owner selected the hold, because its cause is not an
execution-reconciliation cause. The task never ran again, and only a
person's Retry could continue it
> - Recovery from an infrastructure fault must work automatically,
without a person
> - This pull request lets the execution-disposition pass hand that hold
to the existing fresh-continuation fallback
> - The benefit is that the task continues once, in an isolated fresh
run, and the cut-off turn is never replayed

## Linked Issues or Issue Description

**What happened?**
A native run on a Daytona execution environment (native runtime, an
OpenRouter model) started its provider turn. A Daytona request then
failed with `HTTP request timed out after 300000ms waiting for a
response. This is a client-side deadline
(DaytonaConfig.requestTimeoutMs, or the per-call operation/execution
timeout); any operation already started on the server may still be
running.` The run failed with `native_session_interrupted`. The task had
no further run: no automatic retry and no continuation.

**Expected behavior**
The task continues automatically, exactly once, in a fresh run from its
saved work. The cut-off provider turn is not replayed.

**Steps to reproduce**
1. Start a native run for an assigned task. Let its provider turn start
(a `turn.started` event is saved).
2. Make a sandbox request in that turn fail with the Daytona client-side
timeout error.
3. The executor saves the coordinator as `terminal_failure` with
`recoveryMode: ambiguous_state`, blocks the task, and writes an active
board hold with cause `native_session_interrupted`.
4. Run the execution-disposition worker
(`settleUnrecoverableExecutions`). Before this change, nothing happens
and the task stays blocked.

**Paperclip version or commit**
`master` at 9ebc276b42 (observed on a build from 5acf27bc3).

**Deployment mode**
Hosted cloud with a Daytona execution environment.

Causal path:
- The Daytona error is not a named class, so
`nativeSessionFailureSourceCode` returns the generic
`native_session_interrupted`.
- `nativeProviderRecoveryEvidence` returns `ambiguous_state`: provider
events exist, but there is no checkpoint with a provider identity. The
executor then makes the failure terminal on the first attempt (no
same-run resume) and writes a board hold whose cause is
`native_session_interrupted`.
- `unresolvedExecutionDispositions` and `heldExecutionWhere` select only
holds with `EXECUTION_RECONCILIATION_CAUSES` (or a narrow
`resume_native_run` shape). The safe replacement lane accepts
`native_session_interrupted` only for the historical
listener-unavailable case. The assigned-work sweep leaves a task blocked
by an active hold to the hold's owner. So no owner continued the task.

## What Changed

- `server/src/services/execution-recovery-resolution.ts`: the
disposition pass also selects an active watchdog hold with a
restart-class cause (`RESTART_CLASS_FAILURE_CODES`) for a terminal
native run with no retry pending, unless the safe replacement lane owns
that run. It hands the run to `continueFreshInTransaction` and records
the fallback's result on the hold, so a run that does not continue is
checked again only when due.
- `server/src/services/fresh-continuation-fallback.ts`: the fallback
treats an active watchdog hold with a restart-class cause as its own.
When it continues the task, it settles that hold and unblocks the task,
as it does for reconciliation holds.
- New red/green test
`server/src/services/native-runtime/native-client-timeout-continuation.integration.test.ts`.
It drives the real native executor with a provider turn that starts and
then fails with the Daytona client-timeout error.

The cut-off turn is not replayed. The fresh continuation isolates the
old run as it does for every continuation: the old run loses its write
authority, its remote workspace epoch is fenced (or the continuation
gets a new workspace), and the coordinator records `replacementDenied:
fresh_continuation`. The fallback keeps its existing checks:
person-owned causes, exact recovery still under way, and the per-task
hourly cap.

## Verification

- Red on `master`: `npx vitest run
src/services/native-runtime/native-client-timeout-continuation.integration.test.ts`
fails with no continuation recorded.
- Green with this change. The test asserts that the run fails with
`native_session_interrupted` and the Daytona error text in an ambiguous
state, then that two disposition passes record exactly one fresh
continuation, the task goes from `blocked` to `todo`, no active hold
remains, the old run is marked `replacementDenied`, and two
continuation-delivery passes wake the assignee exactly once.
- Focused suites (all tests that use the disposition pass, the
fresh-continuation fallback, or the execution-control schedule, 28
files): 27 files pass. `chat-channels.integration.test.ts` has 9
failures that are unrelated to this change (see the PR comment for the
`master` baseline).
- `npx tsc --noEmit -p server/tsconfig.json` passes.
- `pnpm verify --explain` selects 2751 of 3578 files (a near-full run).
I did not run it locally. CI supplies that coverage.

## Risks

- Behavior change: a terminal native interruption hold that before
stayed with the board now continues automatically in a fresh run. This
is the intended product behavior. The fallback still refuses
person-owned causes and still respects the per-task cap.
- Holds with restart-class causes are now settled by the fallback when
it continues a run. Before, they could stay active next to the
continuation record.
- No migration. No API or UI contract change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits) and code execution for 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.1115.0-canary.9
2026-11-15 08:15:41 +00:00
DottaandClaude Opus 5.5 01c1e708e9 fix(runner): stop a turn that keeps resending a refused tool call and continue fresh (#21734)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Native agent runs call Paperclip tools, and
`RepeatedToolFailureGuard` refuses an exact repeat of a call that
already failed validation twice
> - The refusals are not counted and never end the turn, so a model
whose host drops an argument can resend the same refused call until the
run's wall clock
> - In a recorded restart-chaos wave, an opencode/DeepSeek agent sent
the same `PATCH /api/issues/{id}` through `call_api` 431 times in 40
minutes without `body`; 427 were refused. The run held an agent slot and
delayed other tasks
> - The system knows the next step (stop the turn and continue on a
fresh session), so the harness must own it, with no Retry banner
> - This pull request counts refusals, stops the provider turn after a
bounded number with the classified cause `agent_tool_call_loop`, and
queues an automatic fresh-session continuation that tells the model to
use a dedicated tool
> - It also records the declared argument names that each opencode tool
call delivered, so we can tell whether the bridge or the model drops
`body`
> - The benefit is that a looping agent frees its slot in seconds
instead of 40 minutes, and the task continues by itself

## Linked Issues or Issue Description

**What happened?**
An opencode agent on DeepSeek created two subtasks and then tried to set
their descriptions with `call_api` `PATCH /api/issues/{id}`. Every call
arrived with `operationId`, `pathParams`, `query` and `responseText`,
but without `body`. The guard refused each repeat. The model said "I
need to include body" more than 20 times and kept sending the same call:
431 calls, 427 refused, over 40 minutes. The run stayed active and its
agent slot delayed other queued work.

**Expected behavior**
After a small, bounded number of refusals, Paperclip stops the provider
turn and continues the task automatically on a fresh session, with a
hint to use a dedicated Paperclip tool. The board shows no Retry banner
because the system owns this recovery.

**Steps to reproduce**
1. Run a native agent whose model resends one tool call with a missing
required argument.
2. The guard refuses the third and later identical calls.
3. On master, the refusals never end the turn.

**Paperclip version or commit**
`master` at 6400698a8e.

## What Changed

- `repeated-tool-failure-guard.ts`: counts refusals per exact call and
per run. At 6 refusals of one call, or 20 refusals in the run, it throws
`ToolCallLoopError` (`code: "agent_tool_call_loop"`, tool, counts and
argument names, never values). The message tells the model the turn
stops and gives a short hint.
- `paperclip-runner-tool-authority.ts`:
`scheduleToolCallLoopContinuation` writes one idempotent native
status-wake outbox row (key `agent_tool_call_loop:<runId>`) with
`forceFreshSession: true` and the hint as the wake instruction. The
outbox dispatcher admits it with `allowRunCoalescing: false`, so it
never merges into a deferred comment wake or the active run. An assignee
run uses `issue_continuation_needed`. A completion-review run uses
`native_completion_review` with its review assignment, which the
dispatcher revalidates, so the fresh reviewer session keeps the review.
- `native-session-executor.ts`: the session authority epoch queues that
continuation when the guard raises the loop error. The governed-wait
lookup finds the wake on the next tool event and ends the provider turn
as `yielded` with a `same_agent` continuation, the same way the
connection-tools refresh ends a turn. If the wake cannot be queued, the
refusal still reaches the model and the error is logged.
- `status-decision-committer.ts`: a yielded continuation with that key
binds to the queued wake instead of creating a second one.
- `status-arbiter.ts` and `native-run-finalizer.ts`: a pending review
run that ended through this continuation skips the
`native_review_unresolved` resume recovery, because the queued review
wake owns the next reviewer run.
- `mcp-bridge.ts` and `opencode-proxy-finish-diagnostics.ts`: the
opencode tool-delivery diagnostic records `argumentNames` (only names
declared in the tool's input schema, sorted, at most 1,024 characters of
JSON), `argumentNamesTruncated` and `undeclaredArgumentCount`. Values
and undeclared names are never recorded. The forwarder's closed key
allowlist accepts the new fields and validates them, so a record stays
under its 2,048-character limit.

### Threshold choice

- **6 refusals of one exact call.** The guard already runs a call twice
and then refuses with an explicit correction. Six more refusals (eight
identical attempts in total) give a model that reads errors many chances
to change its arguments. In the recorded run the model never changed
them in 427 refusals, so six refusals end that loop within seconds.
- **20 refusals in the run.** A model can alternate between a few
refused variants and keep each one under 6. Refusals happen only for
exact repeats of a certain validation failure, so a healthy run almost
never reaches 20.

### Previous-release story

The guard counters live in memory for one run's tool authority, as
before. A deploy or restart during a run starts the counters again at
zero on the new process; that only delays the stop. The continuation is
an ordinary wake row. If a server on the previous release finalizes a
run that a new server parked, it does not know the key and queues its
own `same_agent` continuation too; the issue execution lock lets one run
and the other coalesces.

## Verification

- Red then green, `repeated-tool-failure-guard.test.ts`: "after N
refusals the guard raises a turn-stopping loop error" and "stops the
turn once refusals across different calls reach the run limit". Both
fail on master.
- Red then green, `native-session-executor.test.ts`: "a turn whose model
repeats a refused call N times ends with agent_tool_call_loop and
schedules a continuation". With the epoch handling disabled it fails (13
calls instead of 8, nothing parked). Also "keeps the refused call's
error when the loop continuation cannot be queued".
- `paperclip-runner-tool-authority.test.ts`: "queues one fresh-session
continuation outbox for the assignee / a completion reviewer stopped by
a tool-call loop" (real Postgres; idempotent).
- `native-tool-call-loop-continuation.test.ts`: with a comment wake
already deferred behind the looping run, the continuation keeps its own
keyed deferred wake, the comment wake is unchanged, and after release a
run starts with `forceFreshSession` and the loop cause.
- `status-arbiter.test.ts`: a pending reviewer stopped by a loop
releases its checkout without a resume recovery.
- `native-status-arbiter-corpus.test.ts`: the existing wake-binding test
now also covers the `agent_tool_call_loop` key.
- `mcp-bridge-delivery.test.ts` and
`opencode-proxy-finish-diagnostics.test.ts`: argument names are
recorded, values and undeclared names are not, invalid records are
dropped, and a boundary test with 32 names of 64 characters stays
forwardable with `argumentNamesTruncated: true`.
- Server: the six touched test files pass (1755 tests). Runner:
`src/drivers/opencode` and `src/cli` pass (569 tests). `tsc --noEmit`
passes for `server` and `packages/paperclip-runner`.
- `pnpm verify` exits 2 (runner package changes need broad coverage), so
required CI supplies the broad run.

## Risks

- A run that hits the limit ends its turn early. The limits are far
above what a model that reads its errors needs, and the task continues
automatically on a fresh session.
- The fresh session loses the in-turn conversation. The task, its
comments, documents and workspace stay, and the continuation names the
cause and the hint.
- The diagnostic now carries declared argument names. These are schema
names, not values, and the forwarder validates the shape before it
forwards a record.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through 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

Refs #21360

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
canary/v2026.1115.0-canary.8
2026-11-15 01:52:50 -06:00
DottaandClaude Opus 5.5 c7efca1eaf perf(recovery): read an agent's own reporting chain and each pass's review waits once (#21724)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The server runs its background recovery queues on one Node main
thread. Each database statement and each byte returned costs main-thread
time. The target is 1,000 concurrent agents per server.
> - On the idle hosted staging instance, the stranded-task check is the
top remaining cost. Each check read the full agent row (with its
configuration blobs) and then every agent of the company, only to decide
whether this one agent can run. Per check it also opened a
repeatable-read budget transaction for the same company and agent.
> - The org-chain evaluation only looks at the agent's own managers.
Reading the whole company is work proportional to the size of the
company, for an answer that depends on a few rows.
> - The same check also read the external review wait of each in-review
task one task at a time.
> - This pull request reads only the agent's reporting chain (one
recursive query up `reports_to`), gives the stranded check a lean agent
read, and reads the review waits of a pass's tasks in one call.
> - The benefit is half the bytes per check (17.2 KB to 8.6 KB), 87
percent fewer rows, and no per-task review-wait chain for tasks that
wait, with the same answers.

## Linked Issues or Issue Description

No issue exists. This describes the problem with the fields of
`.github/ISSUE_TEMPLATE/enhancement.yml`.

**What existing behavior does this improve?**

The per-task reads of the stranded-task recovery check
(`reconcileStrandedAssignedIssues`) and of every caller of
`evaluateAgentInvokabilityFromDb` and `agentService.getById`.

**Subsystem affected**

Server: issue recovery and agent invokability.

**Current behavior**

`evaluateAgentInvokabilityFromDb` reads `id, company_id, name,
reports_to, status` for every agent of the company on each call.
`getById` does the same for `orgChainHealth`. The stranded check calls
it once per task, after a full-row agent read with the configuration
blobs. On staging at idle these are the `agents where company_id = $1`
read at 4.7/s and the full `agents where id = $1` read at 4.2/s. The
check also calls `listExternalReviewWaits` for one task at a time (the
`chat_message_links` / `chat_github_reviews` reads at about 3/s on
staging).

**Proposed behavior**

Read only the agent's managers, with the same cycle, missing-manager,
cross-company and terminated rules. Read nothing when the agent has no
manager or when its own status already decides the answer. Read the
stranded check's agent with only the fields it uses. Read the review
waits of all tasks of a pass in one call, and use that answer only to
skip a task that waits.

**Reason and benefit**

At idle, the average result size on staging is about 17 KB per
statement. The stranded check is about 22 statements and 17 KB per task,
and it runs about 3 times per second there.

## What Changed

- `server/src/lib/agent-reporting-chain.ts` (new):
`readAgentReportingChain` reads the agent's managers with one recursive
CTE up `reports_to`, limited to the agent's company. `UNION` stops the
walk at a cycle. A root agent costs no statement.
- `server/src/services/agent-invokability.ts`:
`evaluateAgentInvokabilityFromDb` evaluates against the chain, not the
company list. It reads nothing when the agent's own status is not
invokable, because the status then decides the answer and the chain is
not part of it. Every caller benefits with no change: wake enqueue,
queued-run claim, retries, run dispatch, wake-queue promotion,
continuation delivery, task watchdogs, thread interactions, native
completion feedback, native session resumption, native review
participants, agent conversations and recovery.
- `server/src/lib/agent-records.ts`: `getById` computes `orgChainHealth`
from the chain, not from the company list.
- `server/src/services/recovery/service.ts`, stranded check:
- The agent read selects only `id, company_id, name, reports_to, status,
lifecycle_state, lifecycle_holds`, not the full row.
- `hasPersistedDurableWaitPath` takes the pass. When the task is in the
pass, the first in-review task reads the external review waits of every
task of the pass with one `listExternalReviewWaits` call. A task in that
answer waits and is skipped. A task not in that answer is read again
alone, exactly as before, so a missing answer never lets a check go
further than a fresh read would.
- A company-wide call without a pass gets a pass of its in-review
candidates.
- `server/src/services/scoped-deadline-work.ts`: an optional
`beforeChecks(entries)` hook gets the entries of the batch before their
checks run.
- `server/src/services/recovery/pass-reads.ts` (new) and
`server/src/services/recovery/work.ts`: the task queues build a pass
from the batch in `beforeChecks` and give it to each check of that
batch.
- Tests:
- `server/src/__tests__/agent-reporting-chain.test.ts` (new): property
test, see Verification.
- `server/src/__tests__/issue-recovery-pass-reads.test.ts` (new):
statements and bytes per check, per pass and per full worker drain.
- `server/src/__tests__/issue-recovery-review-wait-pass.test.ts` (new):
review-wait answers and reads, see Verification.
- `server/src/__tests__/monthly-spend-service.test.ts`: the
select-sequence stub no longer serves a company agent list to `getById`.
- `server/src/__tests__/helpers/recovery-population.ts` (new): seeds a
company with an org chart, review tasks with succeeded native runs, and
optional paused, terminated and recovery-action tasks.
- `server/src/__tests__/issue-recovery.test-fixture.ts`: an optional
statement meter, installed before the first connection.
- `server/src/__tests__/agent-record-read-projections.test.ts`:
`getById` now makes one typed `agents` select; the chain is a raw query.

### Why the shared review-wait read cannot start or escalate work that a
fresh read would not

- A pass is one coordinator batch: at most 25 checks, one after the
other. Its read is never older than the start of the batch. Nothing is
kept across batches.
- Only the positive answer is used: "this task waits on an external
review or reply", which leads to a skip. A skip only delays the task to
its next check, and the end of a wait sends its own hint.
- A negative answer is not used. The task is read again alone, so every
decision that goes further (an enqueue or an escalation) uses a fresh
read, as today.
- A first version also kept the agent's invokability and the budget
answer for the pass. Review found that a kept permissive answer can
reach an escalation, which does not re-check those facts the way an
enqueue does. That reuse is removed: those reads stay per task. No
authorization, pause, approval or budget check is removed or reordered.

## Verification

- Equality proof (`agent-reporting-chain.test.ts`, embedded PostgreSQL):
- 60 generated org charts, 2 companies each, up to 45 agents. Shapes:
deep chains (depth 44), trees, full cycles and mixed graphs.
- Managers are missing (inserted with foreign keys off), in another
company, terminated, paused or pending approval at random depths. Agent
statuses include an unknown value.
- For each agent, the test compares the old list-based result with the
new result. `evaluateAgentInvokabilityFromDb` deep-equals
`evaluateAgentInvokability(agent, companyRows)`.
`getAgentWorkEligibility` on the chain deep-equals it on the company
list (this is the `getById` path). The test also asserts that every
block reason and every chain-health reason occurred.
- The list-based evaluation has no depth cap (`reporting_chain_too_deep`
is declared but never returned), so the chain read has none either. A
cycle ends the walk in both.
- Mutation check: when the recursive step does not walk up, both tests
fail.
- Review-wait equality (`issue-recovery-review-wait-pass.test.ts`,
embedded PostgreSQL): two tasks with a direct chat reply wait, one task
with an inherited GitHub review wait, one task with none, and one task
with an inherited GitHub review wait in another company. One call for
all of them gives the same per-task answer as one call per task, for
both companies.
- Review-wait reads per pass (same file): the pass makes 2 bound-run
message reads (one shared, one for the task whose candidate is not a
wait) where per-task reads make 3, and 89 statements instead of 91. The
check results are identical. On master the pass is ignored, so the test
fails (3 is not less than 3).
- Statements and bytes (`issue-recovery-pass-reads.test.ts`, 50 agents,
200 review tasks with succeeded native runs and no review waits,
embedded PostgreSQL, statement meter on the client sockets):

  | | master | this branch |
  | --- | --- | --- |
  | One check: statements | 22 | 22 |
  | One check: bytes received | 17,170 | 8,617 |
  | One check: rows | 57 | 8 |
  | 25 checks: bytes | 429,331 | 215,505 |
| Real worker, full company drain (200 checks): statements | 4,414 |
4,422 |
  | Real worker, full company drain: bytes | 3,455,957 | 1,749,701 |
  | Real worker, full company drain: rows | 11,600 | 1,800 |
  | Company agent-list reads per drain | 200 | 0 |

Here no task waits, so each batch pays one extra review-wait statement
(8 per drain). Where tasks wait, the shared read replaces the per-task
review, publication and authorization reads.
- Regression after the review change, embedded PostgreSQL (664 tests):
scoped-deadline-work, heartbeat-process-recovery,
issue-recovery-deadlines, assigned-work-invariant,
recovery-deadline-acceptance, heartbeat-issue-liveness-escalation,
slack-conversation-lifecycle. Also issue-list-review-wait-authorization,
external-review-wait, monthly-spend-service.
- Regression of the first version, embedded PostgreSQL (757 tests):
issue-assignee-invokability-routes, agent-record-read-projections,
issue-graph-liveness-equivalence, heartbeat-paused-assignee-new-task,
heartbeat-process-recovery, heartbeat-issue-liveness-escalation,
assigned-work-invariant, recovery-deadline-acceptance,
issue-recovery-actions, heartbeat-refused-assignment-wake,
failed-continuation-continues-again, agent-invokability,
agent-cross-tenant-authz-routes, heartbeat-stop-queued-task,
issue-tree-pause-resume-run.
- `tsc --noEmit -p server/tsconfig.json` passes.

## Risks

- A test double that gives `evaluateAgentInvokabilityFromDb` an object
with only `select` now needs `execute`, and a select-sequence stub of
`getById` gets one select fewer. CI found one (`monthly-spend-service`),
fixed here.
- A batch with no waiting task pays one extra cheap review-wait
statement.
- This branch and #21729 both touch
`server/src/services/recovery/work.ts` in nearby lines. The second one
to merge may need a small rebase.
- `server/src/services/recovery/service.ts` was already past 1,000
lines. This change adds about 25 lines to it, beside the check it
changes.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file edits, local PostgreSQL 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-15 01:34:08 -06:00
DottaandClaude Opus 5.5 7c0c116edf test(e2e): accept every dependency wake producer for the one automatic resume (#21732)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - When a blocker task is completed, Paperclip wakes the blocked
dependent task automatically
> - Two producers emit that `issue_blockers_resolved` wake: the issue
update route and the issue-graph liveness backstop (plus workspace
finalize); they share one idempotency key and coalesce into one wake run
> - The QA task-dependency-resume journey requires the run's
`contextSnapshot.source` to be exactly `issue.blockers_resolved`
> - On QA both producers emitted 43 ms apart; the run was created once,
but the later backstop wake recorded its source on the run, so the
journey failed a resume that happened exactly once
> - This pull request accepts any of the three producers and keeps every
other resume condition
> - The benefit is that the journey tests the user-visible promise (one
automatic resume caused by this blocker) instead of which internal
producer won a race

## Linked Issues or Issue Description

**What happened?**
QA run (launch 3937) failed task-dependency-resume on
`dependency_one_automatic_resume`. The dependent's activity log shows
`issue.blockers_resolved_wake_emitted` from `issue_update` at
06:59:39.973 and from `issue_graph_liveness_backstop` at 06:59:40.016
with the same idempotency key and the same wake run. Exactly one run
executed, started after the blocker completed, and succeeded.

**Expected behavior**
The journey accepts one automatic, blocker-caused resume regardless of
which producer's label the coalesced run kept.

**Steps to reproduce**
Grade the retained evidence with `contextSnapshot.source =
"issue_graph_liveness.backstop"`: `dependency-one-automatic-resume`
fails although every other condition holds.

## What Changed

- `task-dependency-resume-evidence.ts`: the wake source must be one of
`issue.blockers_resolved`, `issue_graph_liveness.backstop`,
`workspace.finalize` (the producers of this wake reason in
`server/src`).
- Still required: one dependent run, `invocationSource` automation /
`triggerDetail` system, wake reason `issue_blockers_resolved`, the
resolved blocker id, start after blocker completion, committed native
run, no leftover checkout.

## Verification

- Red/green: new cases "accepts the same automatic resume when the
issue_graph_liveness.backstop / workspace.finalize dependency wake
recorded its source" fail before and pass after.
- Existing mutants still fail: "mutation name used as wake source"
(`issue.blocker_done`) and "missing saved wake source".
- `tests/runner-e2e` task-dependency tests: 3 files, 108 tests pass.

## Risks

- Low risk: journey grading only. Separate note: the coalesced run keeps
the last producer's source label; whether it should keep the first is a
provenance question, not addressed here.

## 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
- [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-15 07:29:19 +00:00
DottaandClaude Opus 5.5 41a3520a2f fix(issues): count a blocker covered when its wake already created a queued run (#21731)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A blocked parent task shows "covered" when its blockers have work
that will start by itself, and "needs attention" when a person must act
> - The blocker-attention read counts a blocker as active only through
its current execution run, or through a waiting wake that has not
created a run yet
> - A child whose wake already created a queued run that has not started
matches neither, so the parent shows "needs attention" and lands in the
blocked inbox
> - That work starts by itself when an agent slot frees, so the
attention is false and asks a person to act for no reason
> - This pull request also counts a blocker as active when its waiting
wake points at a queued or running run
> - The benefit is that the board and the blocked inbox stop showing
false attention while queued child work waits for a slot

## Linked Issues or Issue Description

**What happened?**
A parent task was blocked by two child tasks. Each child had a queued
run that a wake had created, and the runs waited for agent slots. The
parent showed `needs_attention` / `attention_required` and appeared in
the blocked inbox. The children started about 25 minutes later and the
parent then finished without a person.

**Expected behavior**
The parent shows `covered` with reason `active_child` while a child's
queued run waits to start.

**Steps to reproduce**
1. Create a blocked parent task with one child blocker that is assigned
to an agent.
2. Insert a queued wake for the child whose `runId` points at a queued
`heartbeat_runs` row, and leave the child's `executionRunId` empty.
3. List blocked tasks. The parent shows `needs_attention`.

**Paperclip version or commit**
`master` at 6400698a8e.

## What Changed

- `server/src/services/issues.ts`: the blocker-attention wake query
left-joins `heartbeat_runs` on the wake's `runId`. A queued or deferred
wake counts as an active path when its `runId` is empty or when its run
is `queued` or `running`.
- `server/src/__tests__/issue-blocker-attention.test.ts`: two tests. One
covers a child whose wake created a queued run that has not started. One
makes sure that a wake whose run already finished does not cover the
blocker.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/issue-blocker-attention.test.ts`: 27 passed.
- Red on master: "classifies a blocked parent as covered when its
child's wake already created a queued run that has not started" fails
with `needs_attention` / `attention_required`. Green with this change.
- Query plan (embedded Postgres, `enable_seqscan = off`): an index scan
on `agent_wakeup_requests_company_payload_issue_idx` (company and
payload issue id), then a nested-loop left join through
`heartbeat_runs_pkey`. The query count does not change, so there is no
N+1.
- `pnpm verify`.

## Risks

- Low risk. The change adds coverage only for a wake whose run is still
`queued` or `running`. A wake whose run finished, failed or was
cancelled stays uncovered, as before.
- The join is a primary-key lookup per wake row, inside the same chunked
query, so the board read cost does not change in a meaningful way.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through 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-15 01:23:38 -06:00
DottaandClaude Opus 5.5 9ebc276b42 test(restart-chaos): let R5 wait out a slow model request and stop calling held wakes undispatched (#21730)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The restart-chaos harness (`tests/restart-chaos`) grades each task
of a chaos wave with rules R1–R6
> - R5 fails a run that stays `running` with no new evidence for more
than 3 minutes (`silent_dead_run`)
> - In wave w-20261115T044649-s7106, task t028 failed R5. Its run was
quiet for 303.6 s (05:22:13.005 to 05:27:16.647) because one DeepSeek
request through OpenRouter was slow. Every sample showed an active
provider turn and no tool running. The run then finished normally.
> - A slow model request is not a dead run. False failures hide real
failures and make the wave number wrong.
> - This pull request lets R5 wait up to 10 minutes while a provider
turn is active and no tool runs. It also stops the release-swap grade
from calling queued wakes "never dispatched" while a live run holds
them.
> - The benefit is a wave grade that counts only real dead runs and real
lost wakes.

## Linked Issues or Issue Description

**Bug description**
R5 reports `silent_dead_run` for a run that waits on one slow model
request. The samples show `providerTurnActive=true` and no tool in
flight for the whole gap. The run then finishes normally. Separately,
the release-swap grade detail says "2 queued wake(s) never dispatched"
for a task whose run was still running. Those wakes wait behind the
active run by design.

**Steps to reproduce**
Grade the t028 samples of wave w-20261115T044649-s7106 with `gradeR5`.
The result is `fail: silent_dead_run 7b51b352… 182s`. Grade a
release-swap task that has a stale running run and queued wakes. The
detail contains "never dispatched".

**Expected behavior**
R5 passes a quiet run while a provider turn is active and no tool runs,
up to 10 minutes. R5 still fails a quiet run with no active provider
turn after 3 minutes, and a provider turn quiet for more than 10
minutes. The grade does not call wakes undispatched while a queued or
running run holds them.

## What Changed

- `grader.ts`: add `PROVIDER_TURN_LIMIT_MS` (10 minutes).
`deadRunningRun` uses this limit instead of the 3-minute
`STALL_LIMIT_MS` when the run sample has `providerTurnActive`. A run
with a tool in flight or a live process is still skipped as before.
- Why 10 minutes: the observed slow request took 303.6 s. Common
provider HTTP clients (the OpenAI and Anthropic SDKs) time out a request
at 10 minutes. After 10 minutes the provider client has given up, so
continued quiet means the run is dead, not slow. A turn whose process
died also keeps `providerTurnActive` set, so the bound still catches it.
- `release-swap-grade.ts`: omit the "N queued wake(s) never dispatched"
note while the task has a queued, running or scheduled-retry run. The
stale-run note stays.
- New fixture `fixtures/t028-slow-provider-turn.json`: the real t028
samples from 05:21:30 to the run's end (116 samples).
- `README.md`: document the provider-turn bound for R5 and the
queued-wake rule.

## Verification

- Red on `origin/master`, green with this change:
- `triggers.test.ts` › R5 live evidence › "does not flag a slow model
request while the provider turn is active with no tool running
(w-20261115T044649-s7106/t028)"
- `triggers.test.ts` › R5 live evidence › "still fails a silent run with
no active provider turn, and a provider turn silent past the
provider-latency bound" (guards: 4 min quiet with no provider turn
fails; 9.5 min quiet with a provider turn passes; 10.5 min quiet with a
provider turn fails)
- `release-swap-grade.test.ts` › "does not report queued wakes as never
dispatched while a run holds them (w-20261115T044649-s7106/t019)" (also
checks that wakes with no live run still get the note)
- `npx vitest run --config tests/restart-chaos/vitest.config.ts`: 71
files, 826 tests pass.
- `npx tsc -p tests/restart-chaos/tsconfig.json --noEmit`: clean.
- No wave was run.

## Risks

- Low risk. The change touches only the test harness grader.
- A run whose provider turn is active but whose process is truly dead
now fails R5 after 10 minutes instead of 3. The fault is still caught,
but later.

> 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`), used 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
- [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>
canary/v2026.1115.0-canary.7 nightly/v2026.1115.0-nightly.0
2026-11-15 01:02:31 -06:00
DottaandClaude Opus 5.5 6400698a8e test(e2e): find the native Plan chip in the Coordinator chat thread (#21727)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The QA Cloud plan-revise-accept journey checks that a person can
revise and approve an agent's Plan
> - It first checks that the saved Plan chip is visible, scoped to a
settled `task-chat-turn` so a live "Writing plan" chip cannot count
> - The Coordinator workspace renders the Plan chip directly in the chat
thread; there is no `task-chat-turn` element and no `data-settled`
attribute
> - So the journey never finds the chip and fails before the person
reviews the plan
> - This pull request also accepts the chip in the chat thread
> - The benefit is that the plan journey reaches the revision and
approval steps it exists to test

## Linked Issues or Issue Description

**What happened?**
On QA Cloud (build 5acf27bc), plan-revise-accept failed with
`journey_operation_failed`, no checks passed, one run. The agent saved a
correct two-step Plan and a revision-bound confirmation. The
confirmation stayed pending until cleanup closed the task, so the
browser never reached it.

**Steps to reproduce**
1. Open the failed journey task on QA (Coordinator workspace).
2. Query `[data-testid="task-chat-turn"][data-settled="true"]
[data-testid="task-chat-plan-preview"]`: 0 matches.
3. Query `[data-testid="task-chat-thread"]
[data-testid="task-chat-plan-preview"]`: 1 visible match, aria-label
"Open Plan revision 1 in task sidebar".

**Expected behavior**
The journey finds the saved Plan chip and continues to "Request
changes".

## What Changed

- `planStageRootSelector(native)`: native root is a settled task-chat
turn or the task chat thread. `expectPlanStageVisible` uses it. The
revision-name check from #21701 is unchanged.

Why this still detects the failure that matters:
`runPlanRevisionAcceptance` waits through the API until every task run
is terminal before this check, and the aria-label must name the exact
revision, which a live "Writing plan" chip does not.

## Verification

- On the live failed QA page: old scope finds 0 chips; new scope finds 1
visible chip whose label matches `planPreviewLabel(1)`.
- `tests/runner-e2e` plan-revision tests: 4 pass (new selector test
included).
- QA Cloud rerun of plan-revise-accept follows after merge and the
harness pin update.

## Risks

- Low risk: journey code only.

## 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
- [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-15 06:12:41 +00:00
DottaandClaude Opus 5.5 61c315ebab perf(chat): keep GitHub review check deadlines on company-wide rebuilds (#21725)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The GitHub chat channel shows a check run on each pull request it
reviews. The review-check sweep (`review-check-work.ts`) keeps one
`github_review_check` action per check. It republishes the check when
its status changes (queued, running, completed) and polls the pull
request head on a saved deadline.
> - Each time the sweep loads its checks, it computes the current check
status of every `received` check (`githubReviewCheckState`: 3–5
statements) to see whether the status changed.
> - Run lifecycle changes anywhere in a company send a company-wide
hint. So the sweep rebuilds every company's checks every 30 s and
recomputes the status of every waiting check, even when nothing about
those checks changed.
> - This pull request keeps the saved poll deadline on a company-wide
rebuild and reads the status only on targeted hints, at startup, and in
`check()`.
> - The benefit is that an idle company with many waiting checks costs
one page read per rebuild instead of 3–5 statements per check.

## Linked Issues or Issue Description

Refs #21705, #21711 (the same class of idle reload in the GitHub
response sweeps).

No issue exists. This describes the problem with the fields of
`.github/ISSUE_TEMPLATE/bug_report.yml`.

**What happened?**

On paperclip.staging at 89de6cbe3e (2026-11-15, 04:47–04:51Z, near idle
at about 0.4 HTTP requests/s), the statements of
`githubReviewCheckState` each ran at about 3/s:

- `select … from chat_github_reviews where endpoint_id … and
repository_id … and pull_number … and head_sha … order by created_at
desc limit 1` (all columns: id, company_id, endpoint_id, issue_id,
run_id, repository_id, …) at 3.04/s;
- `select chat_message_links.comment_id from chat_deliveries join
chat_message_links …` at 3.04/s;
- `select id, status from heartbeat_runs where company_id = $1 and
agent_id = $2 and context_snapshot->>'wakeCommentId' in (…)` at 3.04/s.

Staging has 84 GitHub review checks waiting on runs that have not
started. 84 checks reloaded every 30 s is 2.8 status computations per
second. That matches the observed rate.

**Root cause**

`registerGitHubReviewCheckWork` loads with
`githubReviewCheckReconstructionIntervalMs`, which allows one
company-wide rebuild every 30 s. Run lifecycle changes elsewhere in the
company keep sending `{ companyId }` hints, so the rebuild runs every 30
s. `entry()` calls `githubReviewCheckState` for every `received` row on
every load, only to see whether the status differs from the published
one. A waiting check's status does not change until its review, its run,
its delivery or its connection changes.

**Expected behavior**

A company-wide rebuild reads the waiting checks without recomputing each
status. A change to a check's run or pull request still publishes
promptly.

**Steps to reproduce**

1. Create 30 `received` GitHub review checks whose published status is
`queued`, with a poll deadline 1 hour ahead.
2. Register the review-check sweep. Send a company-wide hint every 30 s.
3. On master, each rebuild runs one page read plus 2–5 statements per
check.

**Paperclip version or commit**

master at 5acf27bc3b.

## What Changed

- `server/src/services/chat-channels/github/review-check-work.ts`:
- A company-wide load (company scope with no endpoint, repository,
number or task) does not call `githubReviewCheckState`. It keeps each
check's saved deadline: the head-poll `retryAt`, or the lease expiry.
Dispatch reads the current status anyway when that deadline comes.
- Startup (no scope) and targeted loads (endpoint, repository, pull
request or task) still read every status, as before. So do `check()` and
dispatch.
- Run lifecycle changes send `{ companyId, issueId }` for the run's
task, and publication lease releases send the pull request scope. Both
still publish a status change at once.
- New `mergeEntry`: an entry from a rebuild that did not read the status
keeps an earlier due time that a status read found. A company-wide
rebuild never postpones a pending publication. `check()` reads the
status again before it dispatches.
- `server/src/services/chat-channels/github/review-check-work.test.ts`
(new, real PostgreSQL):
- `does not recompute the status of every waiting check on each company
rebuild`
- `still publishes a check promptly when its review run starts` (a
task-scoped hint after a review run starts makes only that check due)

- `server/src/__tests__/chat-channels.integration.test.ts`:
- `publishes a local change at once and still recovers a missed head
after backing off` used a company-wide hint to stand for the review run
starting. It now sends the task-scoped hint that a run milestone sends,
and still expects the `in_progress` publication at once.
- `rebuilds GitHub review checks for company-wide hints at most once per
interval` is now `reads no GitHub review check status for company-wide
hints and still reads it for the check's task`. Company-wide hints read
0 statuses. Hints for the check's task still read 1, and hints for
another task or company read 0.

No GitHub check content changes. The published status, title and
conclusion are computed as before.

## Verification

- `pnpm vitest run
src/services/chat-channels/github/review-check-work.test.ts` (server),
30 waiting checks, 4 company rebuilds:
  - master: 244 statements, with 120 check status computations (red).
- this branch: 4 statements (one page read each), with 0 status
computations (green). A task-scoped hint still makes the started check
due at once.
- `pnpm vitest run src/services/chat-channels/github/`: 8 files, 62
passed.
- Related suites (`chat-channels.integration.test.ts`,
`app-private-hostname-gate.test.ts`, `idle-completed-history.test.ts`,
`chat-github-review-repair.test.ts`) filtered to review-check, GitHub,
history and hostname tests: 702 passed before the integration-test
updates below; after updating the two review-check tests, the 15
review-check tests pass.
- `pnpm typecheck` (server): passed.

## Risks

- A status change that sends only a company-wide hint is now published
at the check's next poll deadline, not at the next company rebuild. The
poll backs off to at most 5 minutes. Run lifecycle changes for a review
run carry its task, and connection or configuration changes are also
checked by dispatch, so this affects only hints that name no task or
pull request.
- Startup still reads every status, so recovery after a restart is
unchanged.

> 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, local PostgreSQL tests) and
extended reasoning.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] 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>
canary/v2026.1115.0-canary.6
2026-11-14 23:56:53 -06:00
DottaandClaude Opus 5.5 5acf27bc3b perf(server): read the instance role and membership once per GET request in authorization (#21716)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Every board request goes through authorization, and the server runs
all requests on one Node main thread
> - The cost on that thread is per database statement
> - One `GET /api/issues/:id` makes several authorization decisions (the
issue, its project, mentioned projects, related task edges), and each
decision reads `instance_user_roles` and `company_memberships` again
> - On a task with a blocker and a project mention, that is 4 role reads
and 4 membership reads in the authorization service for one request, all
with the same answer
> - This pull request shares those two reads among the decisions of one
GET or HEAD request
> - The benefit is fewer statements on every polled board read, with no
authorization cache across requests

## Linked Issues or Issue Description

**What existing behavior does this improve?**
`authorizationService.isInstanceAdmin` and `getActiveMembership` read
the database for each decision in a request.

**Subsystem affected**
Server: authorization service and app middleware.

**Current behavior**
`GET /api/issues/:id` for a plain task sends 3 `instance_user_roles`
reads and 3 `company_memberships` reads (1 each in the session
middleware, 2 each in authorization). A richer task sends 5 and 5.

**Proposed behavior**
A new middleware, `authorizationReadScope`, opens a per-request memo for
GET and HEAD requests. For a session actor, it seeds the instance admin
answer that the session middleware read at the start of the same
request. Inside the scope, `isInstanceAdmin`, `getActiveMembership`,
`issueReadSqlCondition` and `projectReadSqlCondition` read each key
once. The plain task now sends 1 role read (the session middleware) and
2 membership reads (1 in the session middleware, 1 in authorization).
The issue list and summaries routes also drop their extra role reads.
Other methods, background work and other callers keep the old reads. The
memo ends with the request, so a revoked membership takes effect on the
very next request.

**Reason and benefit**
Fewer statements per polled read, with the same decisions.

**Breaking changes**
None.

## Memo lifetime rule

- The memo exists only for GET and HEAD requests.
- It wraps `res.writeHead`, `res.flushHeaders` and `res.write` once and
never reassigns them, so hooks that later middleware installs on the
response stay in place.
- It closes at the first of: `res.writeHead`, `res.flushHeaders`,
`res.write`, `finish` or `close`. After it closes, every read goes to
the database. A stream, a long poll, a download or a callback that runs
after the response therefore never uses the memo.
- Each entry is used for at most 2 seconds
(`AUTHORIZATION_READ_MAX_AGE_MS`), then read again. Correctness does not
depend on a list of routes.
- A rejected read is removed from the memo, so the next decision reads
again.
- Nothing is kept across requests.

Long-lived and streaming routes that I checked:
- `GET /plugins/:pluginId/bridge/stream/:channel` (SSE): authorizes once
at connect with `assertBoardOrgAccess` and `assertCompanyAccess` on
`req.actor`. It does not re-authorize per event. The memo closes at
`writeHead`.
- Streaming downloads (`object.stream.pipe(res)` in assets, access and
issue attachments): they authorize before the stream starts. The memo
closes at the first write.
- `POST /board/chat/stream` and `POST
/companies/:companyId/skill-sources/discover` (NDJSON): POST, so no
memo.
- Live events, plugin API, runner and terminal WebSockets: they use
`server.on("upgrade")`, so they do not pass through Express middleware.

## What Changed

- New `server/src/services/authorization-read-scope.ts`:
`authorizationReadScope` (an AsyncLocalStorage scope for GET and HEAD)
and `readOncePerRequest`.
- `authorizationService.isInstanceAdmin` and `getActiveMembership` use
`readOncePerRequest`. The existing batch snapshot memo still comes
first.
- `issueReadSqlCondition` and `projectReadSqlCondition` use the same
`admin:<userId>` key for their instance admin check.
- For `source: "session"` board actors, the scope seeds `admin:<userId>`
with `req.actor.isInstanceAdmin`, which the session middleware read from
`instance_user_roles` in the same request.
- `createApp` mounts `authorizationReadScope` after the actor and Cloud
control middleware.
- `authorizationReadScope` closes the memo when the response starts or
ends, ignores entries older than 2 seconds, and drops rejected reads.
- New exported `readInstanceAdmin(db, userId)`: the one predicate for
`isInstanceAdmin`, `issueReadSqlCondition` and
`projectReadSqlCondition`.
- New test `authorization-request-reads.test.ts`: one role read and one
membership read in authorization per issue read, and a removed
membership gives 404 on the next request.

## Verification

- Red: without the scope, the issue read sends 3 `instance_user_roles`
statements (`expected ... to have a length of 2 but got 3`).
- Green: with the scope, it sends 1 role read and 2 membership reads.
The issue list plus the summaries request send 1 role read each.
- Revocation: delete the membership row, and the next GET returns 404.
HEAD returns 200, then 404 after the revoke.
- Stream: a GET that flushes headers, then re-reads the membership after
it is deleted mid-stream, sees the deletion.
- Background callback: a callback scheduled in a GET that runs after the
response and after a revoke reads again and sees the deletion.
- Age bound: an entry older than 2 seconds is read again. A rejected
read is not kept.
- Seed predicate: for users with an `instance_admin` row, another role
row, and no row, the session middleware value equals
`readInstanceAdmin`.
- Other actors: an agent key, a board key and a cloud tenant actor get
no seeded value.
- Response hooks: a later middleware that wraps `res.writeHead` and
`res.write` keeps working for JSON and streamed responses. This test
fails with a version that restores the original methods.
- Red: with the previous implementation, the stream, callback, age and
rejection tests fail.
- `pnpm exec vitest run` on `access-routes-hidden-floor`,
`access-routes-permissions-upgrade`, `access-service`,
`agent-auth-middleware`, `authorization-privacy-query`,
`authorization-request-reads`, `authorization-run-context`,
`authorization-service`: 8 files, 177 tests pass. Also
`inbox-mine-candidates`, `issue-read-filter-batching`,
`attention-summary-counts`, `issues-unread-inbox`,
`live-runs-batched-reads`, `privacy-production-review`,
`activity-routes`, `authorization-privacy-query`,
`muse-native-visibility`: 224 tests pass (one
`privacy-production-review` test failed once under machine load and
passed on two reruns).
- `pnpm --filter @paperclipai/server typecheck` passes.

## Risks

- This changes where authorization gets two facts inside one request, so
it needs a human review before merge.
- A GET route that changes a membership or an instance role and then
authorizes again before its response starts, within 2 seconds, would see
the earlier value. GET routes do not change memberships or roles. POST,
PATCH, PUT and DELETE requests do not use the memo.
- A board actor built by the session middleware still carries its own
connect-time `memberships` and `isInstanceAdmin` for the life of a
stream. That is the existing behavior, and this change does not affect
it.
- Nothing is cached across requests.

> 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>
canary/v2026.1115.0-canary.5
2026-11-14 22:41:47 -06:00
DottaandClaude Opus 5.5 f33db357f7 fix(ui): let Request changes on a plan always take a revision note (#21721)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - In planning work, an agent saves a Plan document and asks the person
to confirm it with a request_confirmation card
> - The card offers "Request changes"; it opens a revision note only
when the request sets rejectRequiresReason, allowDeclineReason or
declineReasonPlaceholder
> - Paperclip's own plan confirmations (runner plan approval) always set
rejectRequiresReason, but an agent that writes its own confirmation may
not
> - Then "Request changes" rejects the plan at once and the person
cannot say what should change
> - This pull request makes plan confirmations always open the revision
note; the note stays optional unless required
> - The benefit is that a plan can always be sent back with a reason,
and the QA plan journey can complete

## Linked Issues or Issue Description

**What happened?**
On the QA Cloud stack the plan-revise-accept journey failed. The agent
saved a correct two-step Plan and a confirmation bound to the latest
revision, with labels "Confirm" / "Request changes" and
`rejectRequiresReason: false`. Clicking "Request changes" rejected the
plan immediately; no revision note opened.

**Steps to reproduce**
1. Create a request_confirmation that targets the issue's `plan`
document without `rejectRequiresReason`.
2. Open the task chat and click "Request changes".
3. The plan is rejected with no note.

**Expected behavior**
"Request changes" opens the revision note so the person can describe the
change, as for Paperclip's own plan approvals.

## What Changed

- `TaskChatCompactInteractionCard`: `collectsRejectReason` is true for
any plan confirmation (issue_document target with key `plan`). The note
label shows "(optional)" when a reason is not required, and the reject
button stays enabled with an empty note.

## Verification

- Red/green: new `TaskChatInteractionCard.test.tsx` case "opens the
revision note for a plan even when the request does not require a
reason" fails on master (the click rejects) and passes with the change.
- `ui` vitest for `src/components/task-chat` and
`IssueThreadInteractionCard`: 68 files, 1119 tests pass. UI typecheck
clean.
- QA Cloud: the plan journey failed at this step in run 43671188287 (the
only failing product step in a 22/24 run). It will be rerun after
deploy.

## Risks

- Low risk. Only plan confirmations change: one extra step (the note
box) before a plan rejection. Non-plan confirmations are unchanged.

## 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
- [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-15 04:14:27 +00:00
Nicky LeachandClaude Opus 5.5 a78be8b601 feat(native): send launch preparation and run digests to plugin task prepare (#21717)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Environment plugins can run a native Runner as a plugin task, and a
warm session keeps that Runner between turns
> - On each warm turn Core sends the plugin a `prepare` operation with
the full launch requirements for the new run
> - The requirements' `requirementsDigest` covers the run identity, and
the run identity changes on every turn
> - So a plugin cannot tell that only the run moved, and it must redo
its whole preparation every warm turn
> - This pull request gives the plugin two digests: one that stays the
same while its preparation stays valid, and one that names the run
> - The benefit is that a plugin can transfer only the run identity when
nothing it reconciles changed

## Linked Issues or Issue Description

**What existing behavior does this improve?**
The `prepare` operation that Core sends to an environment plugin for a
plugin Runner task, on cold starts and on warm attaches.

**Subsystem affected**
Native runtime, plugin Runner tasks, the Runner launch contract, and the
plugin SDK environment task contract.

**Current behavior**
A warm attach sends the full requirements. The only digest available,
`requirementsDigest`, includes `runId`, `turnId` and `itemId`, so it
changes on every turn even when the launch is otherwise the same.

**Proposed behavior**
Core computes two digests for every `prepare`:
- `preparationDigest`: the launch requirements an environment reconciles
when it prepares a Runner:
  - the runner, lease and session identity;
  - provider, model and settings;
  - the prompt and instruction text;
- the runtime context's instruction and skill bundles, working copy and
connection instructions.

It leaves out the `runId`, `turnId` and `itemId`, and the runtime
context's MCP assignment and binding (with `aggregateDigest`, which
hashes the assignment). MCP reaches the Runner through Core's tool
authority on every run attachment, never through files the environment
publishes. Core already continues a warm session across an MCP-only
change (`nativeRuntimeContextsMatch` with tool refresh). The binding is
also named per run (`native-mcp:<runId>`). So the digest stays the same
across warm turns of one Runner, lease and session, including when the
agent's MCP access changes.
- `runDigest`: `preparationDigest` plus everything it leaves out:
`runId`, `turnId`, `itemId`, and the MCP assignment and binding. It is
unique to one run's launch.

A plugin that advertises `launchDigestVersion: 1` in its task
description gets both fields on `prepare`.

**Reason and benefit**
A plugin can compare `preparationDigest` with its saved preparation and
transfer only the run identity when they match, instead of a full
preparation.

**Breaking changes**
None. Plugins without `launchDigestVersion` get no new fields.

## What Changed

- `packages/paperclip-runner/src/live/runner-provider-launch.ts`: add
`runnerLaunchPreparationDigest` and `runnerLaunchRunDigest`. The
preparation digest drops the MCP assignment and binding; the run digest
takes the full requirements and includes them. Both use the same
canonical JSON as `runnerLaunchRequirementsDigest`, with their own
schema tags so the three digests never collide. Export them from the
package and the server's vendored runner shim.
- `packages/plugins/sdk/src/environment-tasks.ts`: add optional
`preparationDigest` and `runDigest` to the `prepare` operation, and
optional `launchDigestVersion: 1` to the task description. The
capability gates both digests.
- `server/src/services/native-runtime/plugin-runner-task.ts` and
`native-session-executor.ts`: send both digests on `prepare` when the
description advertises `launchDigestVersion: 1`.
- `server/src/services/environment-task-runtime.ts`: recompute both
digests from the requirements, and refuse a `prepare` whose digests are
missing in part or do not match.
- `tests/runner-e2e/source-sdk-public-inputs.json`: refresh the SDK
public source pin.
- Tests:
- the preparation digest is stable across runs and changes when the
runner, lease, session, instructions, model, approval policy or settings
change;
- with a runtime context, an MCP-only change (the run's binding, no
binding, a changed access set) keeps the preparation digest and changes
the run digest;
- a change to the instruction bundle, instruction entry, a skill bundle,
the skill set, the working copy or the connection instructions changes
the preparation digest;
  - the run digest changes per run;
  - Core sends the digests only when advertised;
- the runtime refuses forged or partial digests before it calls the
plugin.

## Verification

- `npx vitest run src/live/runner-launch-preparation.test.ts` in
`packages/paperclip-runner`: 26 passed.
- `npx vitest run src/services/native-runtime/plugin-runner-task.test.ts
src/__tests__/environment-task-runtime.test.ts` in `server`: 160 passed.
- `npx vitest run source-sdk-public-inputs.test.mjs
source-sdk-evidence.test.ts source-sdk-public-type.test.ts` in
`tests/runner-e2e`: 59 passed.
- `pnpm typecheck` in `server` and in `packages/paperclip-runner`:
clean.
- Not run locally: the full suite. CI covers it.

## Risks

Low risk. The digests are new optional fields behind a plugin capability
version. Core computes them and checks them again before it calls the
plugin, so a plugin can rely on them. They prove only that the launch
requirements are unchanged. A plugin that skips work on a match must
still check its own state, such as files it published into the sandbox.
If the runtime context carries values that change per run, the
preparation digest changes too, so a plugin does its full preparation.
That is safe, but the plugin saves nothing. The MCP binding is the one
such value Core sets per run today, and MCP is excluded entirely. A
plugin that does publish MCP configuration into its sandbox must not
rely on this digest for it. Values outside the requirements are not
covered at all: the account identity and credentials, the GitHub broker,
project IDs, and the plugin's own runtime revision. A plugin must keep
checking those itself. A match lets a plugin skip publishing its launch
configuration, not computing the descriptor: `prepare` must still return
a launch whose `requirementsDigest` matches the current requirements,
which carry the current MCP assignment and binding.

## Model Used

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

## 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-14 20:07:54 -08:00
DottaandClaude Opus 5.5 b1e70ab6dd fix(db): recover prepared statements that a pooler or schema change invalidates (#21718)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The server runs every database statement from one Node main thread.
With `prepare: true`, postgres.js sends a statement in one round trip
instead of two, and the CPU cost of each statement is about half
(benchmark from #21707).
> - `DATABASE_PREPARED_STATEMENTS=true` turns on preparation for ORM
queries (#17673). Hosted instances connect through a transaction-mode
pooler (PgBouncer 1.22 or later, Neon `-pooler` hosts), which supports
protocol-level prepared statements.
> - I tested the flag locally through PgBouncer 1.26.1 in transaction
mode. Evictions, server connection churn, `RECONNECT`, transactions,
pipelining, `SET LOCAL`, advisory transaction locks and savepoints all
work. One failure is not acceptable: after a migration changes a column
type, every prepared statement that reads that column fails, for every
client and for every new process.
> - PgBouncer shares one server-side prepared statement by SQL text.
PostgreSQL never repairs a named statement whose result type changed, so
it fails with `cached plan must not change result type` until PgBouncer
drops it. The postgres.js retry prepares the same text again, and
PgBouncer gives it the same broken statement. postgres.js also caches
the failed statement without columns, so the connection throws
`TypeError: Cannot read properties of undefined (reading 'length')` for
that text even after the schema is correct again.
> - This pull request makes the client recover. When a prepared
statement fails with a prepared-statement error, the client stops
preparing that text, retries once without preparation where that is
safe, and counts it. It also caps the number of prepared texts.
> - The benefit is that the flag can be turned on behind a pooler
without a deploy migration that breaks reads. Behavior with the flag
unset or `false` does not change.

## Linked Issues or Issue Description

Refs #17673 (the opt-in), #10795 (the flag), #21707 (the CPU benchmark).

**What happened?**

With `DATABASE_PREPARED_STATEMENTS=true` behind PgBouncer 1.26.1 in
transaction mode (`max_prepared_statements=5`, local PostgreSQL 17), a
change of a column type made every later execution of an affected
statement fail. A new client process failed in the same way. Measured
with the local probe, 20 executions after the change and 10 from a new
process:

| Change | Before: failures | After: failures |
| --- | --- | --- |
| `int` to `bigint`, ORM read outside a transaction | 20/20, new process
10/10 (0A000) | 0/20, 0/10 |
| `varchar` length change, ORM read | 20/20, 10/10 | 0/20, 0/10 |
| Add column, `select *` | 20/20, 10/10 | 0/20, 0/10 |
| `int` to `bigint`, first statement of a transaction | 20/20, 10/10 |
0/20, 0/10 |
| `int` to `bigint`, second statement of a transaction | 20/20, 10/10 |
1/20, 1/10 |
| Table recreated with its original shape, same client | 10/10
(TypeError in `DataRow`) | 0/10 |
| Add column, explicit-column ORM read | 0/20 | 0/20 |

**Expected behavior**

A statement whose pooled prepared statement is stale or lost runs
anyway, and the failure does not reach the caller.

**Steps to reproduce**

1. Run PostgreSQL behind PgBouncer 1.22 or later with `pool_mode =
transaction` and `max_prepared_statements` above 0.
2. Start Paperclip with `DATABASE_PREPARED_STATEMENTS=true` and run a
read of a table a few times.
3. Change the type of a column that the read returns, for example `alter
table ... alter column n type bigint`.
4. Run the read again from the same process or from a new process: it
fails with `cached plan must not change result type`.

## What Changed

- `packages/db/src/prepared-queries.ts`:
- The prepare decision for each `unsafe` query is made when the driver
builds the query, not when the caller creates it, so a query that waits
on a busy connection sees a text that was demoted after it was queued.
- A failure with 26000 (`prepared statement does not exist`), 42P05
(duplicate statement name), or 0A000 `cached plan must not change result
type` demotes the text: the client does not prepare it again in that
process.
- A pooled statement that fails in that way is retried once with
`prepare: false`. Statements in a reserved connection, cursors,
`forEach`, `describe` and queries with `onexecute` are not retried.
- When the failed statement is the first statement that the transaction
ran (only `SET TRANSACTION` before it), the client restarts the
transaction on the same connection: `ROLLBACK`, `BEGIN` with the same
options, the same `SET TRANSACTION` statements, then the statement
unprepared. The callback runs once and receives the result. Tagged
statements and statements in savepoints count toward the execution
order. The client does not restart when another statement of the
transaction is queued, and it never restarts inside a savepoint.
- At most 1,000 distinct texts are prepared for each client and its
private pools. Texts longer than 8 KB are not prepared. Explicit
per-query `prepare` options, simple queries and the flag-off paths are
unchanged.
- `packages/db/src/client.ts`, `packages/db/src/index.ts`: a client and
its dedicated, liveness, checkpoint, file-storage and listener pools
share one state. `preparedStatementStats(db)` returns the prepared,
unprepared, demoted and retried counts.
- `packages/db/src/prepared-queries-postgres.test.ts`: nine tests
against embedded PostgreSQL: restart after a stale plan and after a lost
statement (the callback runs once and its later work commits),
`repeatable read read only` kept after a restart for driver and ORM
transactions, no restart after a later statement, after a tagged first
statement, or for an out-of-order await, a savepoint whose first
statement fails while the outer transaction continues once, the pooled
retry with `.values()`, and the cap.
- `doc/DATABASE.md`, `docs/deploy/database.md`: the cap and the
recovery.

## Verification

- Red/green, `pnpm --filter @paperclipai/db exec vitest run
src/prepared-queries-postgres.test.ts`. With the old
`prepared-queries.ts` (stub stats exports only), the five new tests
fail: two transactions fail with the stale-plan and the
missing-statement errors, the ORM read fails with 42P05, the invalidated
text is prepared again, and 5 texts are prepared where the cap is 2.
With this change, 23/23 pass.
- `pnpm --filter @paperclipai/db exec vitest run` on
`prepared-queries-postgres`, `client-options`, `client`,
`dedicated-connection-pool`, `dedicated-connection-admission`,
`response-capture-postgres`, `lazy-transaction-queries`,
`client-disconnect-replay`: 91/91 pass on the final revision. `tsc
--noEmit -p packages/db` passes.
- 31 server test files with `DATABASE_PREPARED_STATEMENTS=true`
(services, routes, inbox, recovery, heartbeat events, agent auth,
prepared-statement helpers): 829/830 pass. The one failure
(`execution-workspaces-service`, a git-scan timing test) passes alone
with the flag on and off. The machine load average was 9 to 20.
- Local PgBouncer probe (not in CI, because CI has no PgBouncer):
PgBouncer 1.26.1, PostgreSQL 17, postgres.js 3.4.9 (patched), Node 26.4.
The results in the table above, plus 0 failures for 4,800 statements
over 60 distinct texts with `max_prepared_statements=5`, 0 failures with
`pg_terminate_backend` and `RECONNECT` every 25 statements, and 0
failures for transactions with `SET LOCAL`, pipelines of 20 statements,
`pg_advisory_xact_lock` and savepoint rollback.

- Through PgBouncer 1.26.1 (transaction mode,
`max_prepared_statements=5`, 4 server connections) and PostgreSQL 17, at
head 84732c8f67, compared with the master `prepared-queries.ts`. Each
row ran 10 times on its own client, warmed before the migration. "Type"
is `int` to `bigint` under an ORM read; "star" is an added column under
`select *`. Failures before → after:

| Row | Type change | Added column, `select *` |
| --- | --- | --- |
| (a) outside a transaction, same process | 10 → 0 | 10 → 0 |
| (b) first statement of an ORM transaction (callback runs once) | 10 →
0 | 10 → 0 |
| (b) first statement, `begin isolation level repeatable read read only`
| 0 → 0 (the statement was evicted and prepared again) | 10 → 0 |
| (b) first statement, ORM `repeatable read`, `read only` (`SET
TRANSACTION` repeated) | 10 → 0 | 10 → 0 |
| (c) later statement of a transaction, same process | 10 → 1 | 10 → 1 |
| (d) new process after the migration: (a) / (b) / (b) driver / (b) ORM
/ (c) | 10/10/0/0/0 → 0/0/0/0/1 | 10/10/10/10/10 → 0/0/0/0/1 |
| (e) same client after the table is restored: (a) / (b) / (b) driver /
(b) ORM / (c) | 10/10/0/10/10 → 0 | 10 TypeError each → 0 |

Every restarted transaction checked `transaction_isolation = repeatable
read` and `transaction_read_only = on` after the restart. The PostgreSQL
log shows each restart as `ROLLBACK`, `BEGIN` with the same options,
then the statement as an unnamed statement. With 12 clients restarting
at once over 2 server connections and 6 clients of background load,
12/12 transactions succeeded. In the 15 restarts I paired by
`application_name`, the second `BEGIN` ran on the same server connection
as the `ROLLBACK`, because both are sent together. A different server
connection is also safe: only `SET TRANSACTION` ran before the restart
point, and the client repeats it after the new `BEGIN`.
- Silent rollback check through PgBouncer with
`max_prepared_statements=2`: 3 clients ran 600 transactions, each with
an insert and 6 statements over 40 distinct texts, and more distinct
statements between transactions. PgBouncer parsed 6,409 statements on
the server for 1,089 client parses, so it evicted and prepared again the
shared `commit` (`PGBOUNCER_15`) many times. All 600 `COMMIT`s
succeeded, 600/600 rows were present, and no 26000 error was logged. The
silent rollback needs a `DEALLOCATE` on the session, which PgBouncer
does not allow (it closes the client) and Paperclip does not send.

## Risks

- A transaction restart happens below the callback. Code in the callback
before its first statement runs once. The restarted transaction has a
new transaction id.
- A postgres.js behavior that this PR does not change: with driver-level
preparation (the flag `true`, or unset for tagged SQL), the tagged
`commit` of `sql.begin` is a prepared statement. If something
deallocates it on the session, the driver retries `COMMIT` in the
aborted transaction, which PostgreSQL turns into a rollback without an
error. Through PgBouncer this did not happen in 600 transactions with
the `commit` statement evicted repeatedly (see Verification). It needs a
manual `DEALLOCATE` on a direct session.
- A later statement in a transaction still fails once for each affected
text in each process after a migration that changes a column type. The
text then runs unprepared.
- A demoted text stays unprepared until the process restarts. The cap
admits texts in first-use order.
- A client that sends `DEALLOCATE ALL` through PgBouncer is disconnected
by PgBouncer. Paperclip does not send it.
- With the flag unset or `false`, the code path is the same as before.

## Model Used

Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, local PostgreSQL and PgBouncer in a throwaway
container, 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
- [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-14 21:57:04 -06:00
DottaandClaude Opus 5.5 89de6cbe3e perf(server): list skills without a folder transaction when bundled folders exist (#21715)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The board UI polls `GET /api/companies/:companyId/skills`, and the
server runs all requests on one Node main thread
> - The cost on that thread is per database statement, so a polled read
must stay small
> - Each skills list read reconciles the bundled skill folders, and that
opened two transactions with a company advisory lock, even when all
folders already existed
> - A write-path guard must not run a lock and a transaction on every
poll
> - This pull request checks the current folders with a plain read first
and takes the lock only when a folder must change
> - The benefit is a skills list read with no transaction and no
advisory lock, and 13 fewer statements (58 to 45)

## Linked Issues or Issue Description

**What existing behavior does this improve?**
`folderService.ensureBundledCategory` and `pruneEmptyBundledCategories`
always open a transaction and take `pg_advisory_xact_lock` for the
company folders.

**Subsystem affected**
Server: skill folders service, used by the company skills list.

**Current behavior**
Every `GET /api/companies/:companyId/skills` sends 58 statements,
including 2 transactions (BEGIN, lock, reads, COMMIT), even when nothing
changes.

**Proposed behavior**
`ensureBundledCategory` reads the company skill folders once. When the
bundled root exists and the category folder exists with the expected
name, it returns that folder. `pruneEmptyBundledCategories` computes the
empty categories with plain reads and returns when there is nothing to
delete. In all other cases, both functions take the lock and run the old
code, which reads the folders again under the lock. The same request
sends 45 statements with no transaction.

**Reason and benefit**
The polled read stops taking a company lock, and it sends fewer
statements.

**Breaking changes**
None.

## What Changed

- `ensureBundledCategory`: a plain read fast path when the category
folder and the bundled root exist and the name matches. Create and
rename still run under the company folder lock.
- `pruneEmptyBundledCategories`: a plain read pre-check. The delete
still runs under the lock, and it computes the empty set again under the
lock.
- New test `company-skills-list-statements.test.ts`: a warm skills list
read has no transaction and no advisory lock and at most 45 statements;
two concurrent first ensures create exactly one folder; two concurrent
first list requests create no duplicate folder; a renamed category is
repaired and an empty category is pruned through the locked path.

## Verification

- Red: before the change, the warm read had 2 transactions (`expected 2
to be +0`) and 58 statements.
- Green: after the change, the warm read has 0 transactions, no
`pg_advisory` statement, and 45 statements. The response body is equal
to the first read.
- Concurrency: two `ensureBundledCategory` calls at once return the same
folder, and there is exactly one row for the system key.
- `pnpm exec vitest run` on `company-skills-list-statements`,
`company-skills-service`, `company-skills-routes`,
`company-skills-runtime-concurrency`, `company-skills-catalog-service`,
`company-skills` and the folder tests: 215 tests pass. Two
`company-skills.test.ts` tests in "project workspace skill discovery"
fail on my machine with and without this change. They test file system
discovery and do not use the folders service.
- `pnpm --filter @paperclipai/server typecheck` passes.

## Risks

- Low risk. The fast path returns only when the locked path would return
the same folder without a write. Every write still happens under the
lock, after a fresh read.

> 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>
canary/v2026.1115.0-canary.4
2026-11-14 21:42:10 -06:00
DottaandClaude Opus 5.5 30c4d2f4a1 perf(server): read the issue detail with fewer database statements (#21713)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The board UI loads the task page through `GET /api/issues/:id`, and
the server runs all requests on one Node main thread
> - A CPU profile of the server shows that the cost is per database
statement: SQL building, parameter encoding, result parsing and one
socket write each
> - The issue detail read sent 73 statements for a task with two
ancestors, one blocker and a project mention
> - Several of those statements read the issue row again, only to get
values that the route already loaded
> - This pull request passes the loaded issue to those reads, walks the
ancestor chain in one query, and skips reads whose result the response
does not use
> - The benefit is 9 fewer statements on each task page load (73 to 64),
plus one fewer statement for each extra ancestor level, with a
byte-identical response

## Linked Issues or Issue Description

**What existing behavior does this improve?**
`GET /api/issues/:id` reads the same issue row several times in one
request, and walks the ancestor chain with one statement for each level.

**Subsystem affected**
Server: issue routes and the issue, issue reference and project
services.

**Current behavior**
The route loads the issue, then `getRelationSummaries`,
`getCurrentScheduledRetry`, `findMentionedProjectIds`,
`listIssueReferenceSummary` and `getAncestors` each read the issue row
again. `getAncestors` sends one statement for each ancestor. The inbox
archive fields read two activity aggregates even when the issue has no
archive row. The project embed reads the workspace provider catalog, but
the compact embed does not return it. The test fixture request sends 73
statements.

**Proposed behavior**
The route passes the values it already has. The ancestor walk is one
recursive query. The activity aggregates run only when an archive row
exists. The project embed skips the provider catalog. The same fixture
request sends 64 statements, and the JSON response is the same.

**Reason and benefit**
Fewer statements per request means less CPU on the main thread for every
open task page.

**Breaking changes**
None. Other callers of the changed service functions keep the old
behavior, because the new arguments are optional.

## What Changed

- `issueService.getRelationSummaries` and `getCurrentScheduledRetry`
accept an optional known `companyId` and then skip the issue read.
- `issueService.findMentionedProjectIds` accepts the loaded issue
(`companyId`, `title`, `description`).
- `issueService.getAncestors` accepts the known `parentId` and walks the
chain in one recursive query. It keeps the order (nearest first), the
limit of 50, and the stop at a cycle or at a task that is its own
parent.
- `issueService.getActiveInboxArchiveFields` reads the archive row first
and reads the activity aggregates only when an archive row exists.
- `issueReferenceService.listIssueReferenceSummary` accepts an optional
known `companyId`.
- `issueThreadInteractionService.listForIssue` accepts the loaded issue
(`status`, `companyId`, `executionWorkspaceId`). `GET
/api/issues/:id/interactions`, which the board polls, passes it (11 to
10 statements).
- `projectService.getById` accepts `{ workspaceProvider: false }`. The
issue detail route uses it, because `compactIssueProject` never returns
`workspaceProvider`.
- Test helpers: `createStatementCensus` (statements per request, grouped
by statement shape with the server callers), and a board route fixture
with the real session actor middleware. `meterDatabaseStatements` can
record a call stack for each statement.
- New tests: `issue-detail-statements.test.ts` (statement budget,
byte-identical normalized JSON against a fixture file, access rules,
membership removal on the next request, ancestor walk with a cycle) plus
an interactions poll test, and `board-route-statement-census.test.ts`
(census of the polled and page-load board routes).

## Verification

- Red: before the change, the fixture request sent 73 statements, and
the budget test failed (`expected 73 to be less than or equal to 64`).
- Green: after the change, the request sends 64 statements. The
normalized JSON is byte-identical to the fixture file that I wrote
before the change.
- Access: another company's user gets 404, a missing issue gets 404, an
anonymous request gets 404, a hidden issue stays readable for a member,
and a removed membership gets 404 on the very next request.
- `pnpm exec vitest run` on `issue-detail-statements`,
`board-route-statement-census`, `issues-goal-context-routes`,
`issues-service`, `issue-references-service`, `inbox-archive-routes`,
`heartbeat-task-context`, `project-workspace-provider.integration`,
`workspace-provider-failure`, `issue-telemetry-routes`,
`issue-thread-interaction-routes`, `issue-document-restore-routes`,
`heartbeat-referenced-projects`, `project-environments`: 14 files, 414
tests pass.
- `pnpm --filter @paperclipai/server typecheck` passes.
- Interactions: the polled route sends 10 statements instead of 11, with
a response equal to the service result without the known issue.
- Census: `PAPERCLIP_STATEMENT_CENSUS=/tmp/census.txt pnpm exec vitest
run src/__tests__/board-route-statement-census.test.ts` writes
statements per request and the top statement shapes for each board
route.

## Risks

- Low risk. The new arguments are optional, so other callers keep the
old reads.
- When the route passes a known `companyId`, a concurrent delete of the
issue no longer gives a 404 from these sub-reads. The route already
loaded and authorized the issue in the same request, so the response is
the same in practice.
- The JSON fixture file fails when someone changes the issue detail
response. Regenerate it with `PAPERCLIP_WRITE_ISSUE_DETAIL_GOLDEN=1` and
review the diff.

> 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-14 21:42:06 -06:00
DottaandClaude Opus 5.5 f4f4902707 perf(chat): read the run state of a GitHub response sweep page in one batch (#21711)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The GitHub chat channel has two sweeps for request response
comments: the acknowledgement sweep (`acknowledgement-work.ts`) and the
terminal-response sweep (`terminal-response-work.ts`). Each reads pages
of up to 100 requests.
> - For each loaded request, both sweeps call `readGitHubResponseRun`
one row at a time. That is one latest-run statement, plus the run
identity context read and the message link read of
`chatRunSourceMessageId`. A page of 100 requests costs about 300
statements.
> - On paperclip.staging, those two provenance reads ran at about 13/s
each. #21705 stops the idle backlog from being reloaded. This PR makes
the reads that remain cost a constant number of statements per page.
> - The per-row read also had a failure mode. A 403 from one run's
provenance check aborted the acknowledgement sweep's whole page, so no
request of that company was acknowledged until the 403 went away.
> - This pull request adds a batched `readGitHubResponseRuns` and uses
it once per page in both sweeps.
> - The benefit is a constant number of statements per page, and a
provenance failure that affects only its own request.

## Linked Issues or Issue Description

Refs #21705 (the same sweeps; that PR stops reloading requests that
cannot progress).

No issue exists. This describes the problem with the fields of
`.github/ISSUE_TEMPLATE/bug_report.yml`.

**What happened?**

On paperclip.staging (2026-11-15, about 01:45–02:25Z),
`provenanceReads.context` (`select … from run_identity_contexts where id
= $1 and run_id = $2 and company_id = $3 and status = $4 limit $5`) ran
at 13.37/s, and `provenanceReads.link` (`select
chat_conversations.issue_id, chat_endpoints.provider from
chat_message_links join … where chat_message_links.company_id = $3 and
comment_id = $4 …`) ran at 13.20/s. Both GitHub response sweeps reach
them through `readGitHubResponseRun` → `chatRunSourceMessageId(db, run,
{ provider: "github" })`, once for each loaded row. `load()` costs one
page read plus three statements per row. `check()` read the run state
twice for each due request (before and after the acknowledgement).

In the acknowledgement sweep, a 403 from `chatRunSourceMessageId` (for
example, a run whose identity context is no longer accepted) threw out
of `entry()` and aborted the whole page. The terminal sweep already kept
such a row due, so the acknowledgement owner could revoke it.

**Expected behavior**

A page of requests costs a constant number of statements. A failure for
one run affects only the requests of that run.

**Steps to reproduce**

1. Create 120 GitHub response requests on 30 tasks. Give each task an
ended run with an accepted identity context.
2. Register the terminal-response sweep. On master, the first pass costs
one page read plus three statements per row.
3. Mark the requests `received`, revoke one run's identity context, and
register the acknowledgement sweep. On master, the load fails with a
403, and none of the 150 requests is acknowledged.

**Paperclip version or commit**

master at ea8c734cb9 (includes #21705).

## What Changed

- `server/src/services/chat-channels/github/response-run-state.ts`:
- The latest-run subquery and the "woke for this request" check are
built once, from literals (single read) or from the columns of a request
row (batch read). The single read keeps the same query shape.
- New `readGitHubResponseRuns(db, inputs)`. It reads the latest run of
every request of a page in one statement: `unnest(…) with ordinality`
and a lateral latest-run subquery, then a join to `heartbeat_runs` by id
and company. It then calls the existing `chatRunSourceMessageIds(db,
runs, { allowLegacyWakeComment: true, provider: "github" })` once for
the page's distinct runs. That helper reuses `provenanceReads`, so the
scope, status filters and joins are the same as the single check.
Results map back by position. A run whose provenance check is forbidden
gives `{ forbidden }` for its requests only.
- `server/src/services/chat-channels/github/response-execution.ts`:
`githubResponseExecution` takes an optional pre-read state. It throws a
`{ forbidden }` state as the same 403 that the single read throws.
- `server/src/services/chat-channels/github/terminal-response-work.ts`:
`load()` reads each page's run state with one `readGitHubResponseRuns`
call. `check()` reads the run state once: after the acknowledgement it
reads the row only, and keeps a request that is still owed for the next
check, which reads its run state again first.
- `server/src/services/chat-channels/github/acknowledgement-work.ts`:
the same batching. A forbidden provenance check keeps that request due,
so the acknowledgement owner revokes it (`authorization_changed`), and
the rest of the page continues. After an acknowledgement, a still-owed
request keeps the deadline from its own row (retry time, fast-response
expiry or lease).
- Tests:
- `terminal-response-work.test.ts`: `reads a page of waiting responses
in a constant number of statements` and `acknowledges every owed request
of a page when one run's requester provenance changed`.
- `response-run-state.test.ts`: `reads a page of requests in one
latest-run statement with the state each single read returns` compares
the batch with the single read for every seeded binding and wake link.
- `response-sweep-scope.test.ts`: `rebuilds parked requests once per
interval for company-wide hints` counted run-state *statements* as a
proxy for requests reloaded. With batching, one statement reads a whole
page, so the count dropped from 6 to 2 and the test failed in CI. The
behavior it guards must stay: a company-wide rebuild reloads every
eligible request once per interval, and repeated hints inside the
interval reload none. The test now counts the requests that each
run-state read names (the length of a batched read's request arrays, or
1 for a single read). The expectations stay 6 / `[6, 0, 0, 0, 0]` / 6,
so the test still proves the same rebuild behavior.

No GitHub comment behavior changes.

## Verification

- `pnpm vitest run
src/services/chat-channels/github/terminal-response-work.test.ts`
(server), staging-shaped fixtures (120 waiting requests on 30 tasks;
codes null / `acknowledgement_unconfirmed` /
`acknowledgement_superseded`):
- before (#21705 only): the first pass costs 364 statements, with 120
run identity reads. With one revoked context, the acknowledgement sweep
acknowledges 0 of 150 owed requests. The 2 new tests fail (red).
- after: the first pass costs 10 statements, with 2 run identity reads
(per page: page, latest runs, context, link, wait keys). All 150 owed
requests are acknowledged, including the 5 whose provenance is
forbidden. 8 of 8 tests pass (green). All 7 files under
`chat-channels/github/`: 60 passed. `idle-completed-history.test.ts`: 75
passed.
- On master before #21705, the first pass was 362 statements, and every
company rebuild repeated it.
- `pnpm vitest run
src/services/chat-channels/github/response-run-state.test.ts`: 3 passed.
- `pnpm vitest run src/__tests__/chat-channels.integration.test.ts -t
"terminal|acknowledg|GitHub response|response comment|GitHub review"`:
192 passed.
- `pnpm typecheck` (server): passed.
- `pnpm verify` on #21705 selected 2,738 of 3,565 files (close to the
full suite). I relied on the focused runs and required CI, per
AGENTS.md.

## Risks

- The batched latest-run statement must return the same run as the
single read. The equivalence test covers native and legacy bindings,
ties, other agents and other companies.
- `check()` no longer reads the run state again right after an
acknowledgement. A request that is still owed keeps the deadline from
its own row and is read in full at its next check. The acknowledgement
still revalidates everything before it writes.
- A database error still rejects the whole page, as before. Only the 403
provenance decision is isolated per request.

> 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, local PostgreSQL tests) and
extended reasoning.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] 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-14 21:15:08 -06:00
Nicky LeachandClaude Opus 5.5 8cc26221af perf(native): accept a plugin's in-preparation project-auth check on warm attach (#21710)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Environment plugins can run a native Runner as a plugin task, and a
warm session keeps that Runner between turns
> - On a warm turn Core attaches the kept Runner to the new run: the
plugin prepares the new run, then Core checks managed project
authentication
> - A warm attach has no submit step, so Core sends a separate
`check_project_auth` operation after `prepare`
> - That separate operation is one more plugin dispatch and Launcher
round trip on every warm turn, about 0.12–0.18 s, and it is serial
> - This pull request lets the plugin do the check inside `prepare` and
say so, so Core does not send the second operation
> - The benefit is a faster warm turn with the same proof and the same
failure behavior

## Linked Issues or Issue Description

**What existing behavior does this improve?**
The warm attach of a plugin Runner task (`plugin-runner-task.ts`
`prepareLaunch`). When `launched` is true, Core always calls
`checkProjectAuth` after `prepare`.

**Subsystem affected**
Native runtime, plugin Runner tasks, and the plugin SDK environment task
contract.

**Current behavior**
Cold starts fold the check into submit (`projectAuthCheckAtSubmit`).
Warm attaches send `prepare`, then a separate `check_project_auth`.
Measured on a plugin sandbox, the separate operation costs 0.12–0.18 s
on each warm turn.

**Proposed behavior**
The `prepared` result has a new optional flag, `projectAuthChecked`. A
plugin sets it only when it ran the managed project-authentication check
inside this preparation, for this launch's configuration, provider and
projects, and the check allowed them. Core then records the same lease
proof that an allowed `check_project_auth` records, and skips the
separate check.

**Reason and benefit**
One fewer serial round trip on every warm turn. The plugin already runs
the check for this task; this removes a dispatch, not a check.

**Breaking changes**
None. The flag is optional. A plugin that does not set it, or that saw a
refusal, gets the current behavior. Plugins detect the flag with the SDK
schema before they send it.

## What Changed

- `packages/plugins/sdk/src/environment-tasks.ts`: add optional
`projectAuthChecked: true` to the `prepared` result, with a doc comment
that defines it.
- `server/src/services/environment-task-runtime.ts`: when a `prepared`
result has `projectAuthChecked`, record
`runnerTaskProjectAuthValidation` for the launch's configuration,
provider and projects, without `atSubmit`. This is the proof that
`submit` and `read_file` require.
- `server/src/services/native-runtime/plugin-runner-task.ts`: do not
send `check_project_auth` when the prepared result has
`projectAuthChecked`.
- Tests: a warm attach with the flag makes only `prepare`; without it,
`prepare` then `check_project_auth`. The runtime test covers all four
combinations of `projectAuthCheckAtSubmit` and `projectAuthChecked`.

## Verification

- `npx vitest run src/services/native-runtime/plugin-runner-task.test.ts
src/__tests__/environment-task-runtime.test.ts` in `server/`: 157
passed.
- Not run locally: full typecheck and full suite. CI covers them.

## Risks

Low risk. Core trusts the flag the same way it trusts a plugin's
`check_project_auth` answer and `projectAuthCheckAtSubmit` today. A
refusal still goes through Core's own check, so the conflict error is
unchanged. The plugin side ships separately and sends the flag only when
its SDK accepts it.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, code search, tracing queries).

## 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-15 03:13:48 +00:00
DottaandClaude Opus 5.5 b5ba548112 feat(server): add an instance-admin server metrics endpoint for the scale ramp (#21708)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The scaling plan
(`doc/plans/2026-11-13-thousand-concurrent-agents.md`) has a finish line
that a real-agent ramp harness checks (#21695)
> - Four finish-line criteria need numbers from inside each server
process: main-thread CPU, run event lateness, agent API time before the
handler, and missed lease renewals
> - The server had no way to give them, so every harness run was at best
"incomplete"
> - This pull request adds one instance-admin endpoint that returns
those numbers per process over a short sliding window, off by default,
and connects the harness to it
> - The benefit is that a ramp run can measure every server criterion it
can see, with near-zero cost when on and no cost when off

## Linked Issues or Issue Description

Refs #21695

**Subsystem affected**

Server (instance routes, run event append, native lease renewal),
database client (statement counter), and the scale-ramp harness in
`scripts/scale-ramp/`.

**Problem or motivation**

The scale-ramp harness reads `PAPERCLIP_SCALE_METRICS_URL`, but the
server has no endpoint for it. The criteria `main_thread_cpu`,
`run_event_lateness_p99`, `agent_api_pre_handler_p99` and
`lease_renewals_missed_zero` are therefore always "not measured", and no
run can pass.

**Proposed solution**

Add `GET /api/instance/server-metrics`. It returns a JSON snapshot of
one server process over the last 50 to 60 s. Only an instance admin can
read it. The env flag `PAPERCLIP_SERVER_METRICS` (read once at start,
default off) turns on collection and the route. Off, the path answers
404 and no collector starts.

**Alternatives considered**

- The postgres.js `debug` option for the statement counter: rejected,
because it captures a stack (`new Error()`) for every query.
- Process CPU from `process.cpuUsage()` as `mainThreadCpu`: rejected,
because it includes GC and libuv threads. It is returned as `processCpu`
instead, and `mainThreadCpu` reads the main thread from `/proc` (Linux
only, null elsewhere).
- Default on: the measured cost is negligible (numbers below), but the
event-loop monitor wakes the process every 20 ms when idle, and this is
a new instance-wide surface. It stays off; the runbook says how to turn
it on for a ramp run.

## What Changed

- `server/src/services/server-metrics.ts`: a per-process collector. It
uses `performance.eventLoopUtilization()`, `monitorEventLoopDelay` (20
ms), `process.cpuUsage()`, the main thread's
`/proc/self/task/<pid>/stat` on Linux, and six 10 s buckets of native
`perf_hooks` histograms. One unref'd timer rotates the buckets. Nothing
on the hot path awaits, allocates per call or does I/O.
- `server/src/routes/instance-server-metrics.ts`: `GET
/api/instance/server-metrics`, guarded by the existing
`assertInstanceAdmin` (the check that `/instance/database-backups` and
other instance routes use). It returns numbers, a random per-process
`processId`, `uptimeSec`, `buildRevision` and `windowMs`. It returns no
SQL, names, IDs or hostnames.
- `server/src/app.ts`: when the flag is on, two middlewares time agent
API requests from arrival to the API router, the route is mounted, and
shutdown stops the collector. When the flag is off, nothing is mounted.
- The snapshot also carries `dedicatedConnections` from
`dedicatedDbConnectionStats()` (#21693): `limit`, `inUse`, `waiting` at
request time and `peakInUse`, `queued`, `overLimit`, `nestedOverLimit`
since start. The harness ignores it today; it shows dedicated-connection
queueing in a restart burst.
- `packages/db/src/statement-count.ts` and
`lazy-transaction-queries.ts`: a Drizzle logger that increments one
counter per statement replaces Drizzle's no-op logger. No edit to
`client.ts`.
- `paperclip-control-plane-port.ts`: one call records runner `emittedAt`
to committed row for each committed (not duplicate) runner event.
- `native-execution-lease.ts`: one call counts a lease whose renewal
deadline passed.
- Harness: missed lease renewals are summed per `processId` (several
processes, or a restart, no longer cancel out). A metrics URL on the
target origin gets the board token in the `Authorization` header;
`PAPERCLIP_SCALE_METRICS_TOKEN` still overrides it, and another origin
gets no token.
- Contract: `scripts/scale-ramp/server-metrics.fixture.json` is the
serializer's own output. A server test asserts the serializer produces
exactly this file, and a harness test parses it and checks every field.
- `rules/company-scope-exceptions.mdc`: adds the snapshot as an
instance-wide exception with its reason. The runbook in the plan doc
documents the path, the flag, the credential and each field.

| Field | Provided | Source |
| --- | --- | --- |
| `mainThreadCpu` | yes (Linux; null elsewhere) |
`/proc/self/task/<pid>/stat` utime+stime |
| `eventLoopUtilization` | yes | `performance.eventLoopUtilization()` |
| `eventLoopDelayP99Ms` | yes | `monitorEventLoopDelay`, highest 10 s
p99 in the window |
| `statementsPerSecond` | yes | Drizzle logger counter (not BEGIN/COMMIT
or raw driver calls) |
| `poolWaitP99Ms` | absent | postgres.js has no cheap hook for queue
time |
| `runEventLatenessP99Ms` | yes (null with no events) | runner event
append |
| `agentApiPreHandlerP99Ms` | yes (null with no agent requests) |
arrival and router-entry middlewares |
| `leaseRenewalsMissed` | yes, counter since process start | native
lease deadline timer |

## Verification

- `cd server && npx vitest run
src/__tests__/instance-server-metrics-routes.test.ts
src/__tests__/server-metrics.test.ts`: through `createApp` on the
embedded test database. 200 with the exact field set for an instance
admin; 403 for a company owner who is not an instance admin, for an
agent key, and unauthenticated; 404 and no collector when the flag is
off; values move after agent requests, statements, a late run event and
a missed renewal; the body has no IDs, keys or SQL.
- `cd server && npx vitest run
src/services/native-runtime/native-execution-lease.test.ts
src/services/native-runtime/paperclip-control-plane-port.test.ts
src/__tests__/api-server-timing.test.ts`: the lease and run-event hooks
(red/green checked for the lease hook by removing the call).
- `cd packages/db && npx vitest run src/lazy-transaction-queries.test.ts
src/client-options.test.ts`: the counter counts statements inside
transactions and savepoints.
- `node --test scripts/scale-ramp/scale-ramp.test.ts` and `tsc -p
scripts/scale-ramp/tsconfig.json`: 38 pass, including the fixture
contract and the board-token header.
- `node server/scripts/typecheck-layers.mjs` and `tsc --noEmit` in
`packages/db`: pass.

Overhead, measured on a shared, loaded laptop (load average 8 to 20),
median with min and max:

| Measure | Off | On |
| --- | --- | --- |
| Logger call per statement (5M calls x 7) | 0.28 ns (0.24 to 0.97) |
3.36 ns (3.32 to 6.16) |
| CPU per `select 1` statement, embedded Postgres (3,000 x 10) | 28.7 us
(20.3 to 42.4) | 32.3 us (20.7 to 45.5) |
| CPU per HTTP request, client and server in one process (2,000 x 6) |
67.0 us (40.4 to 107.4) | 64.2 us (40.9 to 83.3) |
| Idle process CPU, 5 s x 3 | 0.01% of a core (0.00 to 2.21) | 0.08%
(0.05 to 0.09) |
| Record one run event (Date.parse + histogram) | - | 148 ns (135 to
188) |
| One snapshot | - | 55 us |

The statement and request differences are inside the run-to-run spread.
The direct cost is about 3 ns per statement, against about 30 us of CPU
per statement.

## Risks

- Low risk. Off by default; off, only the statement counter runs, and it
costs one increment more than Drizzle's no-op logger.
- `mainThreadCpu` assumes Linux USER_HZ of 100 and is null on other
platforms. The harness then uses `eventLoopUtilization`.
- Run event lateness compares the runner's clock with the server's
clock, so clock skew adds to it. Negative values count as zero.
- With several processes, each request reaches one process. The harness
keeps the highest gauge and sums counter growth per process, but a
process it never samples is not seen.
- The statement counter does not count BEGIN/COMMIT or raw postgres.js
calls.

> 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, in Claude Code with
tool use (shell, file edits, 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
- [ ] 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-14 21:13:45 -06:00
DottaandClaude Opus 5.5 554e6d415c fix(restart-chaos): credit a follow-up only to a run that started a provider turn, and post a missed follow-up after the run ends (#21692)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The restart-chaos harness runs staging-mix waves across server swaps
and grades each task for duplicate side effects, extra turns and
follow-up delivery
> - In one wave, the grader reported two false failures
> - Task t005: the grader credited a follow-up to a run that failed
before its provider turn. It then counted the run that really served the
follow-up as a duplicate completion and an extra turn
> - Task t009: the agent finished before the follow-up window opened.
The harness never posted the follow-up, but the grader still required
the post
> - False failures hide real regressions, so the grader must match what
the product did
> - This pull request credits a follow-up only to a run that started a
provider turn, and posts a missed follow-up after the run ends
> - The benefit is that both false failures go away, and the t009 case
still tests the product: the product must answer the late follow-up

## Linked Issues or Issue Description

Refs #21598

**What happened?**
In wave `w-20261114T231451-s7110`, two tasks failed on harness defects,
not product defects.

- t005 (`T:completion_once`, a duplicate side effect and an extra turn):
run 76f30f70 was woken for follow-up comment 3f6a9eb9. It failed before
any provider turn, so the agent never received the comment. Recovery run
fdf1f793 served the comment. It added the FOLLOWUP line and did not post
DONE again (DONE comments = 1). The grader credited 76f30f70 with the
answer and flagged fdf1f793 as a second completion and an extra turn.
- t009 (`T:follow_up_posted`): the follow-up was due at 23:25:19. The
harness posts only during a swap overlap (opened 23:28:02.7) or at the
85% point (about 23:29:15). The agent finished at 23:27:56.0, so the
harness never posted. The grader still required the post.

**Expected behavior**
- t005 grades one completer (60bdd4dc) and no extra turn. fdf1f793 is
the run that answered the follow-up.
- t009 gets its follow-up after the run ends. The grade then requires
the product to answer it.

**Steps to reproduce**
1. Build wake evidence with three runs: a done run, a run woken by a
follow-up comment that has no provider turn, and a recovery run that
re-completes.
2. Grade with `gradeStagingMix`, `completedAtAnchor` and
`runsAfterDone`.
3. Drive `stagingMixStep` with the t009 timings: the run ends before the
overlap and before the 85% point.

## What Changed

- `tests/restart-chaos/wake-evidence.ts`: record `providerTurnStarted`
for each run. It is true when the run has a `turn.submitted`,
`turn.accepted` or `turn.started` run event.
- `tests/restart-chaos/follow-up-delivery.ts`: a run with
`providerTurnStarted: false` does not receive its comments. The comments
carry to the next run that starts a provider turn. That run is the
answering run. Add `undeliveredFollowUpRuns`. Evidence without the field
keeps the old behavior.
- `tests/restart-chaos/staging-mix-retry.ts`: `runsAfterDone` does not
list a run that failed before it could deliver a follow-up as an extra
turn.
- `tests/restart-chaos/staging-mix.ts`: when no run is active after the
hold or the 85% point, `stagingMixStep` posts the follow-up after the
run ended. It records the post as an after-end follow-up, so
`after_end_follow_ups_served` requires an agent reply and the ledger
line. The `follow_up_posted` detail says "after the run ended".
- `tests/restart-chaos/observer.ts`: a staging-mix task with an unposted
follow-up does not finish yet.
- Tests and `tests/restart-chaos/README.md`.

## Verification

- Red on master, green with the fix:
- `a follow-up whose run failed before any provider turn
(w-20261114T231451-s7110 t005) > credits the follow-up to the run that
served it, with one completer and no extra turn`
- `... > lets only the serving run re-complete, and still fails a later
recovery run that answers nothing`
- `staging-mix board step > posts a follow-up the run finished before as
an after-end follow-up the product must answer (w-20261114T231451-s7110
t009)`
- `staging-mix board step > does not post an after-end follow-up between
runs before the during-run window closes, or while a run is queued`
- `TaskObserver > does not finish a staging-mix task whose run ended
before its planned follow-up was posted`
- Guards that still grade as failures on master and with the fix:
- `... t005 > still fails a recovery re-completion when the run that
received the follow-up started its provider turn`
- `a done the server rejected as incomplete > keeps a run woken by
recovery after a real completion as an extra turn and a duplicate
completion (G5c t004)` (#21598)
- `completion_once truth table: a later completion that answers nothing`
- `wake evidence against real PostgreSQL` now checks
`providerTurnStarted` false, then true after a `turn.started` event.
- `npx vitest run --config tests/restart-chaos/vitest.config.ts
--maxWorkers=3`: 71 files, 823 tests pass.
- `tsc -p tests/restart-chaos/tsconfig.json --noEmit`: clean.
- Not run: a new wave. The wave's database is gone, so the real t005
evidence cannot get `providerTurnStarted` from the new query. The tests
use the real t005 and t009 values.

## Risks

- Low risk. The change affects only the restart-chaos harness.
- A run that failed after `turn.submitted` but before the provider read
the input counts as a delivery. This keeps the grader strict: it can
report a false duplicate, but it cannot hide a real one.
- A staging-mix task with a planned follow-up that cannot be posted now
waits until its deadline instead of resting. The grade still reports the
post errors.

## Model Used

- Anthropic 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-14 21:12:52 -06:00
DottaandClaude Opus 5.5 45125f7748 test(server): stop the accounting identity child from timing out on loaded runners (#21712)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The server CI runs the general test suite in 12 shards on shared
runners
> - One accounting test fails at random on unrelated pull requests and
passes on re-run
> - Each failure costs a full re-run of the shard and the `verify` job,
and it teaches people to re-run instead of read
> - The test spawns two helper processes that load about 1,400
TypeScript modules under a 5 second kill timer
> - This pull request makes the helper processes plain `node` processes,
so they do not load the server module graph
> - The benefit is that the test no longer depends on runner load, and
it still uses real exited processes

## Linked Issues or Issue Description

**What happened?**
`server/src/services/run-cost-accounting.test.ts > run cost accounting
work > normal accounting Retry reconstructs an uncommitted legacy
receipt after its real controller and child exited` failed in "General
tests (server (5/12))" three times on 2026-11-15 (UTC), each with the
retry also failing:
- PR #21687, head `2172a5b26a`, job 132643921517
- PR #21687, head `6a1d2fb0ef`, job 132650244103
- PR #21678, head `fc0e96f23c`, job 132663296537

Every failure has the same assertion:
`AssertionError:
{"exitCode":null,"signal":"SIGTERM","timedOut":true,...,"stderrTail":"accounting-identity:program-entered\naccounting-identity:module-imported\n"}:
expected null to be +0`
In five of the six failed attempts, the child stopped after
`module-imported` and before `birth-read`. In one attempt, the child
printed its result but the 5 second timer fired before it exited.

**Expected behavior**
The test passes on a loaded runner. The helper processes are not under
test. Only the accounting Retry decision is under test.

**Steps to reproduce**
1. Slow each module load in the child by 8 ms with an `--import` hook in
`NODE_OPTIONS`. The test passes `NODE_OPTIONS` to the child. This
simulates a loaded runner.
2. Run `npx vitest run src/services/run-cost-accounting.test.ts -t
"normal accounting Retry"` in `server/`.
3. On `master` the test fails with the same `timedOut: true` assertion
as CI.

**Root cause**
The child ran `node --import tsx/esm -e "await
import('controller-process-identity.ts'); await
currentProcessStartedAtMs(); ..."`. That import pulls in
`@paperclipai/shared` and `@paperclipai/db` source through tsx, which is
737 modules. On Linux, `readProcessStartedAt` also dynamically imports
the full runner package shim
(`server/src/vendor/paperclip-runner/index.ts`) to call the 30-line
`/proc` reader. That adds 652 more modules. tsx transpiles all of them
in a cold process under a 5 second `timeoutSec`. On a shared CI runner
this crosses 5 seconds.

**Production impact**
None. In the built server, the runner package is already loaded at boot,
and `currentProcessStartedAtMs()` on Linux reads `/proc` once per
process and caches the result. The cost exists only in a fresh tsx
process that imports source.

## What Changed

- The accounting identity helper child is now `node -e` with no tsx
loader and no module imports. It installs a `SIGUSR2` handler, prints
`ready`, and waits.
- When the test sees `ready`, it reads the child start time with the
product function `observedProcessStartedAt(pid)` and then sends
`SIGUSR2`. The child exits with code 0.
- The test builds the recorded `ControllerProcess` (random boot id,
child pid, `currentProcessSpaceHash()`, observed start time). These are
the same values the child computed for itself before. The child process
is still real, has its own process group, and has exited before the
Retry checks run.
- No retries, skips or timeout changes. The 5 second guard now covers a
plain `node` start, which takes about 40 ms.

## Verification

- Red on `master` with the slow-load hook: `Tests 1 failed`, `timedOut:
true`, the same assertion as CI.
- Green with this change and the same hook: `Tests 1 passed`.
- Full file without the hook: `npx vitest run
src/services/run-cost-accounting.test.ts` passes 34/34.
- Helper loop, 30 runs per variant, macOS, 18 cores with 36 busy-loop
processes (load average about 56):
- old child (macOS path): 29/30 exited in 5 s, p50 2,020 ms, p90 2,234
ms, max 5,172 ms
- old child plus the runner import (as on Linux CI): 29/30, p50 3,663
ms, p90 4,411 ms, max 5,023 ms
  - new child: 30/30, p50 38 ms, p90 43 ms, max 46 ms
- The full test under the same stress: 6/6 before and 6/6 after on
macOS. macOS uses the `ps` path and does not load the runner package, so
this loop does not show the Linux failure. The helper loop and the
slow-load repro do show it.
- `npx tsc --noEmit -p server/tsconfig.json` passes.
- Other tests with the same pattern:
`native-controller-source-digest.test.ts` also spawns a tsx child, but
with a 60 second timeout. It is not the same cause, so this pull request
does not change it.

## Risks

- Low risk. Only one test changes. No product code changes.
- The test no longer checks that a separate process computes its own
identity stamp. That was not the purpose of this test. Other tests cover
`currentControllerProcessStamp()`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edit, 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
- [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-14 21:10:11 -06:00
DottaandClaude Opus 5.5 92308f839d test(e2e): use the Coordinator task panel, inbox and plan controls in QA journeys (#21701)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The QA Cloud product journeys check real user paths on a hosted test
stack
> - #19360 (2026-11-05) made the Coordinator workspace standard; its
task side panel starts with no tabs, and the header control opens a tab
chooser
> - The journeys were written for the classic panel, which opened
straight on Properties, and for older inbox and plan controls
> - On QA the smoke suite passed 8 of 24 journeys; 13 failures trace to
these out-of-date journey steps
> - This pull request updates the journeys to use the shipped
Coordinator controls the way a person does
> - The benefit is that the QA journeys test the product again instead
of failing on removed controls

## Linked Issues or Issue Description

**What happened?**
The QA staging smoke suite passed 8 of 24 journeys. 13 failures come
from journey steps that target the classic UI:
- Task side panel: the journeys click "Show properties" and expect
property rows. In Coordinator the click opens a tab chooser ("Open a
side panel tab"), and the user picks Properties or Artifacts. The
product's own e2e tests (`tests/e2e/artifact-tab-arrival.spec.ts`,
`artifact-uploads.spec.ts`, `disconnect-resilience.spec.ts`) and the
chat-catalog runtime cases already use the chooser.
- Inbox: desktop Coordinator inbox rows show unread state as a bold
title and have no per-row "Mark as read" button
(`doc/plans/2026-11-06-chat-contacts-pins.md`). The `r` shortcut marks
the hovered row read on the Mine view.
- Plan: the Coordinator Plan chip is named "Open Plan revision N in task
sidebar", not "Open Plan revision N".

**Steps to reproduce**
1. Run `pnpm test:e2e:runner -- --target-config <managed local config>`
with task-properties, task-edit-lifecycle, task-document-persistence and
project-task-context.
2. See 0/4 pass on master; each stops at the tab chooser.

**Expected behavior**
The journeys reach the same saved-state checks as before through the
shipped controls.

## What Changed

- New `product-journeys/task-panel.ts` helper: opens the side panel and
selects a tab (Properties or Artifacts) from the chooser, an open tab,
or the "Open a new tab" button. It waits for the page instead of a
single non-waiting visibility check, and does not close an already open
panel.
- task-properties, task-edit-lifecycle, task-dependency-resume,
project-task-context and task-document-persistence (and routine/agent
journeys that reuse `openDocumentAuthoring`) use the helper.
task-properties reopens the panel after reload before it checks "You".
- inbox-triage: when the row has no visible "Mark as read" button, open
the Mine view, blur search, hover the row and press `r` (as
`tests/e2e/coordinator-inbox-views.spec.ts` does).
- Plan journey: `planPreviewLabel()` accepts the optional " in task
sidebar" suffix and still requires the exact revision.
- No product code changes. An earlier revision of this PR changed "Show
properties" to select Properties; it is reverted because the product e2e
suite asserts the chooser is the intended design.

All saved-state assertions are unchanged: assignment, labels, status,
documents, read state and plan revision are still read back through the
API, so a broken feature still fails.

## Verification

- Real browser journeys on a managed local instance against unmodified
master UI: 4/4 pass (task-edit-lifecycle, task-properties,
task-document-persistence, project-task-context); 0/4 before.
- Inbox fallback checked by hand on a local instance: an unread task on
the Mine view became `isUnreadForMe=false` after blur + hover + `r`.
- `tests/runner-e2e` unit tests for product-journeys and plan-revision:
47 files, 1240 tests pass. The task-properties contract test now models
the chooser and asserts the opener and the Properties option are used
before assignment and after reload. New `planPreviewLabel` test covers
revision 12 vs 1 and a missing revision.
- QA Cloud rerun follows once the QA harness pin moves to a master
commit that contains this change.

## Risks

- Low risk: test code only. If the chooser changes again, the helper
fails visibly at the panel step.

## 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
- [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-15 03:08:23 +00:00