Commit Graph
2712 Commits
Author SHA1 Message Date
DottaandPaperclip 451a6ecf24 Merge current master into PAP-10341 branch
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-11 02:13:32 +00:00
DottaandPaperclip d7d52e0b89 Merge tool-access PR hardening into PAP-10341 branch
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-11 02:13:29 +00:00
b8fb81dee9 fix(gemini-local): treat token-overflow as a fresh-session signal (#4932)
## Thinking Path

The same 2026-04-30 audit that produced PR #4118 (`Invalid session`
regex extension) and the ENOTFOUND classifier (#4931) identified a third
stuck-session pattern: **13 failures in 7 days, all on a single agent
(Ernest)**, with stderr matching:

```
_ApiError: {"error":{"code":400,"message":"The input token count exceeds
the maximum number of tokens allowed 1048576","status":"INVALID_ARGUMENT"}}
  at ChatCompressionService.compress
```

The root cause is that gemini-cli's `ChatCompressionService` blew the 1M
token context limit **during its compression step itself**. Resuming the
same session ID will hit the same wall on the next attempt — the session
is effectively dead the same way it is when "Invalid session identifier"
fires (PR #4118).

## What Changed

Extends the `isGeminiUnknownSessionError` regex in `parse.ts` with two
phrases:
- `exceeds\s+the\s+maximum\s+number\s+of\s+tokens`
- `input\s+token\s+count\s+exceeds`

Both trigger the **existing** fresh-session retry path in
`execute.ts:596` — no new code path. Same extension pattern as PR #4118.

## Verification

- `npx vitest run --project @paperclipai/adapter-gemini-local` → 14/14
pass (11 in `parse.test.ts` + 3 existing in `execute.remote.test.ts`)
- 2 new tests cover the token-overflow patterns
- `pnpm --filter @paperclipai/adapter-gemini-local typecheck` → clean
- Audit query against `heartbeat_runs.stderr_excerpt` confirms regex
matches all 13 occurrences

## Stacking

This PR is stacked on top of #4931 (the ENOTFOUND classifier) which adds
the `parse.test.ts` file. If #4931 merges first, this PR's diff is just
the regex + 2 tests. If this PR is reviewed first, please merge #4931
first to avoid touching the same test scaffolding twice.

## Risks

- **Low.** Single-line regex extension. No new code paths.
- The session-reset path is well-trodden (PR #4118 in flight).
- If a non-Gemini caller produces a stderr containing "exceeds the
maximum number of tokens" by coincidence, they would trigger one
unnecessary fresh-session retry. Not plausible in the gemini-cli output
context where this stderr is sourced.

## Model Used

Claude Opus 4.7 (1M context), Anthropic SDK via Claude Code CLI.

## Checklist

- [x] Thinking path traces from audit data to single-line regex change
- [x] Model specified
- [x] No duplicate of planned core work
- [x] Tests pass locally
- [x] Tests added (2 new)
- [x] N/A — server-side regex
- [x] Internal pattern; no docs change
- [x] Risks documented
- [x] Will address Greptile + reviewer comments before merge
- [x] I searched the GitHub PR list for similar PRs and confirmed this
is not a duplicate (related: #4118 covers the "Invalid session
identifier" regex; this PR extends the same regex with token-overflow
phrases)

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

---------

Co-authored-by: Devin Foley <devin@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>
canary/v2026.611.0-canary.0
2026-06-10 19:10:29 -07:00
Dotta fc09704d60 Fix signing secret env typing 2026-06-10 22:55:18 +00:00
Dotta 50fffe6f9f Fix tool gateway signing test isolation 2026-06-10 22:49:32 +00:00
Dotta 4a9aa1d1e0 Set tool signing secret in gateway tests 2026-06-10 22:46:37 +00:00
b853ce5183 Fix heartbeat task-session reuse when agent model changes (#4195)
## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - Heartbeats wake agents and resume prior adapter task sessions so
work is continuous.
> - A persisted task session can contain adapter-specific state (for
Codex, a resumable thread/session) created under the agent's
then-current model.
> - When an operator changes an agent's configured model, the next run
should not blindly reuse a session created under a different model —
context window, capabilities, and prompt assumptions may differ.
> - The existing wake reset logic handles wake reasons
(forceFreshSession, comment wakes, etc.) but not model drift between
current agent config and persisted task-session metadata.
> - This pull request adds model-aware task-session reset and persists
the configured model into task-session metadata.
> - The benefit is that heartbeat runs reliably honor the current agent
model configuration and avoid stale session/model mismatches.

## Linked Issues or Issue Description

**What happened?**

After an operator changes an agent's configured model (for example,
swapping a Codex agent from one model variant to another), the heartbeat
reuses the persisted adapter task session that was created under the
previous model. The new model never takes effect on resume — the run
continues on the prior session and prior model assumptions.

**Expected behavior**

A model change in agent configuration should invalidate the persisted
task session for that agent and force a fresh session start on the next
run, so the configured model is the one actually used.

**Steps to reproduce**

1. Run an agent with model `A` so it persists an adapter task session
under model `A`.
2. Change the agent's configured model to `B`.
3. Trigger a heartbeat for the same issue/agent.
4. Observe: the run resumes the prior task session (still under model
`A`) instead of starting fresh under model `B`.

## What Changed

- Added task-session model metadata support in heartbeat session
handling via `__paperclipConfiguredModel`.
- Persisted the current configured adapter model into
`agent_task_sessions.sessionParamsJson` whenever heartbeat upserts
task-session state.
- Added `shouldResetTaskSessionForModelChange(...)` to explicitly detect
model drift between current config and persisted session metadata.
- Updated run startup logic to force a fresh session when model drift is
detected, with a clear reason message in runtime warnings.
- Strips the internal `__paperclipConfiguredModel` key from
`sessionParamsJson` before it is forwarded to adapters so the metadata
stays internal.
- Added focused tests in
`server/src/__tests__/heartbeat-workspace-session.test.ts` covering
model-drift reset behavior, non-reset cases, and the strip helper.

## Verification

- `pnpm --filter @paperclipai/server test
src/__tests__/heartbeat-workspace-session.test.ts`
- `pnpm --filter @paperclipai/server typecheck`

## Risks

Low. Sessions without persisted model metadata are not reset (backward
compatible). The model key is namespaced (`__paperclip...`) to avoid
colliding with adapter-forwarded params. Drift detection only fires when
both current config and persisted metadata are present and differ.

## Model Used

Claude (Opus 4.6) — used to design the metadata persistence, add the
drift detection helper, and write unit coverage.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots (N/A — no UI changes)
- [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 (in progress)
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Devin Foley <devin@paperclip.ing>
canary/v2026.610.0-canary.9
2026-06-10 15:40:39 -07:00
Dotta d03bd6cc4d Isolate applications CRUD e2e company 2026-06-10 22:37:45 +00:00
Dotta 2d6238bb70 Harden tool action argument handling 2026-06-10 22:32:10 +00:00
Dotta 2fa0e12aab Fix tool access CI fallout 2026-06-10 22:20:55 +00:00
c32193c85e test(codex-local): cover EEXIST race rejection with mismatched symlink (#5269)
## Thinking Path

> - The `codex-local` adapter sets up a per-company Codex home with an
auth symlink. Between `lstat` and `symlink` there is a race where two
concurrent setups can both try to create the same symlink, surfacing
`EEXIST`.
> - Master already handles this at runtime via `createExpectedSymlink`,
which accepts `EEXIST` only when the raced-in entry resolves to the
expected source, and ships a regression test for the tolerated-race path
(symlink already points at the right place).
> - The symmetric path — `EEXIST` raised by a symlink pointing somewhere
else — must stay strictly rejected so a future refactor cannot silently
weaken the guard.
> - This PR locks that in with a single additive test. No production
code change.

## What Changed

- Added one regression test in
`packages/adapters/codex-local/src/server/codex-home.test.ts` that
injects an `EEXIST` whose raced-in symlink target points at a different
file, and asserts:
  - `prepareManagedCodexHome` rejects with `code: "EEXIST"`.
- The mismatched symlink is left on disk (we do not blindly overwrite
the raced-in entry).

Complements the existing "treats a concurrently-created expected auth
symlink as success" test already on master.

Refs #5240 (Stack B — codex-home adapter session/auth handling).

## Verification

- `pnpm --filter @paperclipai/adapter-codex-local exec vitest run
src/server/codex-home.test.ts` — passes.
- `pnpm --filter @paperclipai/adapter-codex-local typecheck` — clean.

## Risks

- Test-only change. No production code is modified.

## Model Used

- Provider: Anthropic
- Model: Claude (Opus 4.7)
- Mode/capabilities: tool-using coding agent with shell execution and
test 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
- [x] I searched the GitHub PR list for similar PRs and confirmed this
is not a duplicate

Co-authored-by: Devin Foley <devin@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>
canary/v2026.610.0-canary.8
2026-06-10 15:15:39 -07:00
Dotta ad70e4183b Fix application delete e2e seeding 2026-06-10 22:15:31 +00:00
DottaandPaperclip 56b6e87e57 Fix tool access test fallout after master merge
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 22:15:10 +00:00
DottaandPaperclip a48051ca14 Fix tool access test fallout after master merge
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 22:14:02 +00:00
Dotta 485d2ddd56 Merge remote-tracking branch 'origin/master' into PAP-10341-paperclip-needs-good-permissions-around-mcp-servers-consider-natoma-and-make-a-plan 2026-06-10 22:09:03 +00:00
Dotta a77b4165a7 Merge branch 'PAP-10341-paperclip-needs-good-permissions-around-mcp-servers-consider-natoma-and-make-a-plan' into pap-10854-tool-access-merge 2026-06-10 22:06:05 +00:00
DottaandClaude Opus 4.8 9c65ebfcf8 Harden application delete against concurrent connection creation (PAP-10824)
DELETE /tool-applications/:applicationId pre-checked for connections and
then deleted in a later statement. Because tool_connections.application_id
was ON DELETE CASCADE, a connection created in that gap was silently
cascade-deleted instead of forcing the promised 409.

Switch the FK to ON DELETE NO ACTION so the database fails closed: an
application with connections can never be deleted, and a concurrently
inserted connection (which takes a FOR KEY SHARE lock on the parent row)
forces the delete to raise a foreign_key_violation rather than cascade.
NO ACTION (end-of-statement check) rather than RESTRICT (immediate) keeps
company teardown cascading cleanly.

The service still pre-checks for a friendly 409 with connectionCount, and
now also translates a 23503 violation on the connection FK into the same
409 so the race surfaces the conflict instead of a 500.

Regression tests: the raw delete is rejected and both rows survive (the
old cascade would have silently dropped the connection), and a company
delete still cascades application + connection away.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 16:26:29 +00:00
DottaandPaperclip 6c2e79bcd3 QA: add PAP-10820 applications CRUD e2e spec
Covers Phases 2/3/4 of PAP-10805:
- Phase 2: edit round-trip + friendly duplicate-name conflict
- Phase 3: Disable/Archive/Reactivate with impact-summary confirm; verifies
  the new deny_disabled_application reason via /tools/policy/test
- Phase 4: 409 guard for connected apps + clean delete + table refresh

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 16:21:07 +00:00
DottaandClaude Opus 4.8 3fa9d1e935 Add e2e smoke for application delete dialog (PAP-10817)
Drives the live tools/applications page: seeds a connection-free
application and a connection-bearing one, opens the row-actions Delete
dialog for each, and asserts the safe-delete copy vs. the
connections-blocked guard message. Doubles as the screenshot capture
for the handoff.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 16:11:19 +00:00
DottaandClaude Opus 4.8 6f2490afbe Add guarded application delete (Phase 4, PAP-10817)
DELETE /tool-applications/:applicationId with board-only auth + company
check mirroring the PATCH route. Guards with 409 when the application
still has connections (no force-cascade in v1) and writes a
tool_application.deleted activity log entry. Adds deleteApplication to
the UI client and a destructive confirm dialog in the row actions menu
that surfaces the connection-guard guidance inline on 409.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 16:06:01 +00:00
DottaandPaperclip a446a67850 Fix duplicate tool application rename conflict
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 15:57:05 +00:00
Dotta fb4d7cf221 Add application edit actions 2026-06-10 15:36:42 +00:00
DottaandPaperclip 401d82f6c4 Unify tool applications and connections UI
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 15:28:47 +00:00
f3db7b88ea Clear stale checkoutRunId on run finalization and add backstop sweeper (#6008)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The issue subsystem holds per-row lock columns (`checkoutRunId`,
`executionRunId`, `executionAgentNameKey`, `executionLockedAt`) that
gate checkout, ownership, and release
> - When a heartbeat run terminates, `releaseIssueExecutionAndPromote`
clears the execution-lock columns but stale checkout locks could remain
attached to dead runs in edge paths
> - The original fix closed the finalization, checkout, release, and
sweeper paths, but PR CI exposed one more process-loss retry path where
a queued retry advanced `executionRunId` while leaving `checkoutRunId`
pinned to the failed run
> - This pull request closes the asymmetry: terminal-run cleanup and
process-loss retry recovery release dead checkout locks while preserving
live execution ownership
> - The benefit is permanent, automatic self-heal of stale lock columns
and fewer false checkout 409s requiring board intervention
> - Related upstream issue: #6007

## Linked Issues or Issue Description

Refs #6007.

Duplicate/related PR search performed on 2026-06-10 with query
`checkoutRunId process loss retry stale checkout lock
repo:paperclipai/paperclip`.

Related PRs found and reviewed for overlap:

- #7727 `fix(heartbeat): atomically advance checkoutRunId on
process-loss retry`
- #7707 `test: cover same-agent stale checkout adoption`
- #3068 `fix: clear checkoutRunId when releasing issue execution lock`

## What Changed

- `server/src/services/heartbeat.ts` `releaseIssueExecutionAndPromote`:
extend the per-issue update to also null `checkoutRunId` when it matches
the terminating run id. WHERE clause scoped to `executionRunId = run.id
OR checkoutRunId = run.id` for idempotence.
- `server/src/services/heartbeat.ts` process-loss retry: when queuing
the retry run, move `executionRunId` to the retry and clear the failed
run's `checkoutRunId` so the dead run no longer owns checkout.
- `server/src/services/issues.ts`: add `clearCheckoutRunIfTerminal`
helper, symmetric to `clearExecutionRunIfTerminal`. No assignee/status
precondition. Wired into `checkout`, `assertCheckoutOwner`, and
`release`. Exported on the issue service.
- `server/src/services/recovery/service.ts`: add `sweepStaleIssueLocks`.
Scans `issues` where `checkoutRunId IS NOT NULL OR executionRunId IS NOT
NULL`, joins each referenced run, and clears all lock columns on issues
whose referenced runs are all terminal or missing. Emits one
`issue.stale_lock_cleared` activity log row per cleared issue.
- `server/src/services/heartbeat.ts`: re-export the sweeper on the
heartbeat facade.
- `server/src/index.ts`: invoke `sweepStaleIssueLocks` in both the
startup recovery sequence and the periodic heartbeat timer chain.
- Tests: route-level coverage of the new self-heal path on the next
checkout attempt, service-level sweeper coverage, and heartbeat recovery
assertions that terminal process-loss cleanup releases `checkoutRunId`.

## Verification

```bash
pnpm --filter @paperclipai/server typecheck
pnpm --filter @paperclipai/server exec vitest run \
  src/__tests__/recovery-stale-issue-lock-sweep.test.ts \
  src/__tests__/issue-stale-execution-lock-routes.test.ts
NODE_ENV=test pnpm exec vitest run src/__tests__/heartbeat-process-recovery.test.ts -t "queues exactly one retry when the recorded local pid is dead|does not block paused-tree work when immediate continuation recovery is suppressed by the hold"
NODE_ENV=test pnpm exec vitest run src/__tests__/heartbeat-process-recovery.test.ts
```

All listed local checks pass. The new and updated tests cover:

- Run termination clears `checkoutRunId` when it points at the
terminating run.
- Process-loss retry clears the failed run's `checkoutRunId` while
assigning `executionRunId` to the queued retry.
- A different agent calling `POST /api/issues/:id/checkout` on an issue
whose prior owner died self-heals via `clearCheckoutRunIfTerminal` and
succeeds.
- Sweeper clears stale lock columns for issues whose run row is
terminal.
- Sweeper leaves issues alone while the referenced run is still running.
- Sweeper leaves issues alone when `executionRunId` is still running
even if `checkoutRunId` is terminal.
- Sweeper is idempotent; second pass clears nothing.

Manual reproduction of the original bug shape:

1. Create an issue assigned to agent A, set `status='in_progress'`,
`checkoutRunId=R1`, `executionRunId=null`, where `heartbeat_runs.status
= 'failed'` for `R1`.
2. Reassign to agent B and move to `status='todo'`.
3. Before this PR: agent B `POST /checkout` returns `409 Issue checkout
conflict` indefinitely. After this PR: succeeds, lock columns rewritten
to agent B's current run id.

## Risks

- Low. All clears are scoped by run id, so they only fire when the lock
column unambiguously points at the terminating or terminal run. No
schema change. No migration. No API surface change.
- Behavioral shift: an issue that previously stayed `in_progress` with a
dead `checkoutRunId` after run termination now self-heals. Downstream
code that reads stale `checkoutRunId` as a proxy for recent run history
should already be reading `executionRunId` or the `heartbeat_runs`
table.
- Sweeper cost: one indexed scan per recovery tick over rows where
`checkoutRunId IS NOT NULL OR executionRunId IS NOT NULL` plus a single
batched `heartbeatRuns` lookup per candidate. Negligible at expected
cardinality; further bounded by the existing recovery cadence.

> 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`.

This is a bug fix, not a feature. No roadmap overlap.

## Model Used

- Claude (Anthropic), model ID `claude-opus-4-7`, extended-thinking off,
tool use enabled.
- OpenAI Codex, GPT-5-based coding agent, tool use enabled, used for the
follow-up process-loss retry fix and PR body update.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Dotta <bippadotta@protonmail.com>
canary/v2026.610.0-canary.7
2026-06-10 09:33:21 -05:00
c297ba2a80 fix(codex-local): replace stale auth.json copy with symlink on prepare (#5028) (#5240)
## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - codex_local runs Codex CLI under a per-company "managed home" so
multiple companies don't trample on each other's session state
> - For `auth.json` specifically, the managed home keeps a SYMLINK to
the user's real `~/.codex/auth.json` rather than a copy — Codex refresh
tokens rotate and are single-use, so any copy goes stale the moment the
source rotates and every subsequent run dies with `401
refresh_token_reused`
> - Older Paperclip versions copied `auth.json` instead. After
upgrading, `ensureSymlink()` saw a regular file at the target, hit `if
(!existing.isSymbolicLink()) return;`, and silently kept the stale copy
> - This pull request makes the upgrade path self-healing inside
`ensureSymlink()` itself: when the target is a regular file, unlink it
and create the symlink, since the target lives under the
Paperclip-managed home and is safe to delete. Directories are skipped to
avoid `EISDIR` on Unix (and inconsistent behavior on Windows)
> - The benefit is operators who upgraded from a copy-based version stop
getting refresh-token-reused failures without having to manually purge
`companies/<id>/codex-home/auth.json`, and the healing is
defense-in-depth even outside the `prepareManagedCodexHome` cleanup path

## What Changed

- `packages/adapters/codex-local/src/server/codex-home.ts` —
`ensureSymlink()` previously bailed out of the
`!existing.isSymbolicLink()` branch, leaving any pre-existing regular
file untouched. Now unlinks and recreates the symlink in that branch via
the existing `createExpectedSymlink()` helper (preserves the EEXIST
race-tolerance behavior added in #5119). A guard skips directories so
the call never throws `EISDIR` and aborts `prepareManagedCodexHome`.
Inline comment explains the safety: target is always under the
company-scoped managed home
(`<paperclipHome>/instances/<id>/companies/<companyId>/codex-home/`),
never the user's real `~/.codex`.
- `packages/adapters/codex-local/src/server/codex-home.test.ts` — adds a
regression test for #5028: pre-seed a stale copy at the target, run
`prepareManagedCodexHome`, assert the target is now a symlink and reads
through to the fresh source. The existing concurrent-symlink test is
preserved.

## Verification

```
pnpm --filter @paperclipai/adapter-codex-local exec vitest run
# Test Files  8 passed (8)
# Tests       26 passed (26)
pnpm --filter @paperclipai/adapter-codex-local exec tsc --noEmit
# clean
```

Manual repro flow that the regression test mirrors:
1. Create a stale copy: `echo '{"token":"old"}' >
<managedHome>/auth.json`.
2. Rotate source: `echo '{"token":"new"}' > ~/.codex/auth.json`.
3. Trigger any codex_local run — `prepareManagedCodexHome` is called
from the execute path, the managed file is now a symlink to the source,
and the CLI sees the fresh token.

## Risks

- **Low risk.** The new branch only fires when the target file is a
regular file (the upgrade path) — a pure copy that Codex couldn't have
written, since Codex never writes into the managed home. Operators in
steady-state on the symlink-based version are unaffected.
- The `fs.unlink` only runs against the per-company managed-home path,
never the user's real `~/.codex`. Inline comment makes this guarantee
explicit.
- A directory at the auth.json path is left in place (no silent `EISDIR`
crash) — this requires operator inspection rather than autonomous
deletion.
- The healing uses `createExpectedSymlink()` so it remains tolerant of
EEXIST races with concurrent prepare calls (the concurrent-symlink test
still passes).
- No DB / migration / schema impact.

## Model Used

- Anthropic Claude Opus 4.7 (claude-opus-4-7), via Claude Code CLI with
extended tool use (Read / Edit / Bash / Grep). No extended-thinking
budget consumed beyond default.

## Checklist

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

Fixes #5028.

---------

Co-authored-by: Devin Foley <devin@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>
canary/v2026.610.0-canary.6
2026-06-10 06:50:20 -07:00
DottaandPaperclip 0739570fa5 Prefix tools board routes
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 13:22:58 +00:00
DottaandPaperclip 4726aa99a8 Move tools UX into company sidebar
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 13:12:23 +00:00
dfd3ed44c5 fix: auto-retry on Claude "Could not process image" 400 during session resume (#3276)
## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - The Claude-local adapter resumes prior sessions via `claude --resume
<session-id>` so work continues across heartbeats.
> - When a resumed session contains an image whose content is no longer
accessible, Claude returns a 400 "Could not process image" — but the
session itself is poisoned and will keep returning the same error on
every resume.
> - The existing retry path only catches the "unknown session" 400 case;
image-processing 400s on resume fall through and the run fails for the
user.
> - This PR adds an `isClaudeImageProcessingError` detector mirroring
`isClaudeUnknownSessionError` and wires it into the same fresh-session
retry branch in `execute.ts`.
> - The benefit is that a poisoned-image resume self-recovers by
retrying once with a fresh session, exactly like the existing
unknown-session path.

## Linked Issues or Issue Description

Fixes #3275
Refs #3123

## What Changed

- Added `isClaudeImageProcessingError()` in
`packages/adapters/claude-local/src/server/parse.ts` that matches `Could
not process image` in 400 error messages.
- Wired the new detector into the existing session-resume retry branch
in `packages/adapters/claude-local/src/server/execute.ts` alongside
`isClaudeUnknownSessionError`.
- Retry only fires when `sessionId` is present (i.e. we were resuming),
so fresh-session runs that hit the same error are not retried (no
infinite loop).

## Verification

- `pnpm --filter @paperclipai/adapter-claude-local test` covers
`parse.ts` patterns and the resume-retry decision branch.
- `pnpm --filter @paperclipai/adapter-claude-local typecheck`

## Risks

Low. Behavior change is narrowly additive: a previously-fatal 400 on
resume now triggers a single fresh-session retry. No effect on
fresh-session runs, unknown-session retries, or non-image 400s.

## Model Used

Claude (Opus 4.6) — used to mirror the existing unknown-session pattern
and verify the guard against infinite loops.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots (N/A — no UI changes)
- [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 (in progress)
- [ ] 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: Devin Foley <devin@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>
canary/v2026.610.0-canary.5
2026-06-10 06:00:05 -07:00
DottaandPaperclip e9cb8e2b28 chore: update MCP access branch onto master (PAP-10797)
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:52:57 +00:00
DottaandPaperclip 8bb16a93db fix(ui): Overview denials metric card + Connections test fixture (PAP-10778)
Address QA findings from PAP-10789:
- Overview 4th MetricCard is now "Denials (24h)" with a "N denied · M failed"
  sub-line (matching the v2 spec mockup), pairing with the denials table
  below, instead of the redundant Trust rules count.
- Fix ConnectionsTab.test.tsx secret fixture to use valid SecretProvider /
  SecretManagedMode literals (local_encrypted / paperclip_managed); was
  failing tsc in the integrated tree.

Typecheck (tsc -b) clean; Connections + transcript tests pass.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:31 +00:00
DottaandClaude Opus 4.8 452a72f180 fix(ui): drop duplicate page-level EnforcementBanner on Tools (PAP-10790)
OverviewTab and RuntimeTab each render their own EnforcementBanner
(info data-driven / warning trust-tier respectively), so the
page-level banner in ToolsAccess stacked a second identical info
banner above the Overview metrics and above Runtime's warning.
Move banner ownership fully into the tabs and remove the
ToolsAccess-level call + now-unused import.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 12:49:31 +00:00
DottaandPaperclip f203d1a0d8 feat(ui): Connections v2 — dense table + vault credential picker + inline probe (PAP-10785)
Apply the Connections deltas from the v2 punch list (PAP-10778):

- Replace the connection cards with a dense table: connection (mono
  URL/cmd subtitle), application, transport pill, Health pill
  (HealthBadge), catalog count + 'refreshed N min ago', and Test /
  Refresh / Tools row actions. Per-connection catalog counts are fanned
  out via cached useQueries (same pattern as ApplicationsTab) since no
  company-wide aggregate endpoint exists.
- New-connection dialog now renders a vault-reference credential picker:
  selecting a secret shows its 'vault://provider/key@version' reference
  and a 'Free-text secrets are not accepted' help line. The persisted
  shape stays the structured McpConnectionCredentialRef (secretId) — the
  vault:// string is display-only.
- Inline Probe panel runs before activation (auto-probes after draft
  create): health-check + catalog discovery, showing a status pill,
  tools-discovered count, probe round-trip latency, and quarantined
  count, following the LoadingState/ErrorState rhythm.

Adds a component test and a storybook story for the table/dialog.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:31 +00:00
DottaandClaude Opus 4.8 4041289c7f feat(ui): Agent-detail Tools tab — effective-access banner + Why these tools panel (PAP-10788)
Surface 09 of the PAP-10771 v2 punch list. Adds a Tools tab to the agent
detail page that communicates the agent's server-resolved tool access:

- EnforcementBanner (tone=info): "Effective access — server resolved." —
  the list is what the gateway will accept, profile/policy edits reflect
  within ~5s, and the prompt can narrow but never expand it.
- Allowed-tools table (tool name, capability + risk pills, source connection).
- "Why these tools?" side panel: bound profile(s) (deep link to Profiles),
  governing policies with their #N evaluation order (deep link to Policies),
  and a "Denied tools (suppressed)" section derived from the full company
  catalog minus the allowed slice.

Extracted into ui/src/pages/AgentToolsTab.tsx (kept the heavy AgentDetail
module out of the unit test) with coverage in AgentToolsTab.test.tsx. The
incidental transcript run-decision wiring already present in AgentDetail.tsx
is the sibling "transcript tool rows" delta and rides along untouched.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 12:49:31 +00:00
DottaandPaperclip d28508fbe3 feat(ui): Action approval card v2 — stale variant + bindings + signed payload + mobile (PAP-10787)
New ui/src/components/actions/ActionCard.tsx implementing the issue-thread
approval card per the PAP-10771 v2 spec (surfaces 11/12/99):

- Real Card: avatar + "Coder requested approval to call" header + outcome pill;
  body with tool name + risk/capability pills; bindings table (application +
  manifest version, connection, catalog sha256, signed payload sha256); JSON
  input mono block; "Why I'm asking" referencing the policy by number; footrow
  with expiry icon + Edit & re-sign / Deny / Approve.
- Stale variant (PAP-10400 hardening): amber border, catalog-hash-mismatch
  banner, previous catalog hash struck through next to the current one, and
  Approve rendered disabled until re-issuance.
- Mobile (390×844) via ActionCardMobile: identical content, full-width buttons
  stacked Approve / Deny / Edit & re-sign, 70px bindings label column.
- New exported BindingsTable (two-column mono key/value) lives inside the card
  and is reusable in the audit row drilldown.

Showcased in the design guide and a Storybook story; unit tests cover the
PAP-10400 security states (signed payload + expiry always shown, stale Approve
disabled, struck-through prior hash) and the mobile button order. Typecheck and
the new component tests pass.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:31 +00:00
DottaandClaude Opus 4.8 378bcafb6b feat(ui): Profiles v2 two-pane + allow-list Source column (PAP-10786)
Adopt a master/detail two-pane layout for the Tools & Access Profiles tab.
Left rail lists profiles with a 'N tools · bound to M agents' subtitle and an
active-item background; the right pane shows the selected profile's Targets,
Effective scope summary, selectors, and a resolved Allow list sub-table.

The Allow list resolves each profile's selector entries against the company
tool catalog into concrete tools with columns: mono tool, application,
capabilities (RiskBadge/CapabilityBadges reuse), risk, and the new Source
column. Source distinguishes explicit grants from pattern matches (wildcard
tool name, application, connection, or risk selector) so a tool pulled in by
e.g. 'slack.list_*' is no longer a foot-gun nobody can explain.

Adds ProfilesTab.test.ts covering the resolution logic: explicit vs pattern
sourcing, explicit-beats-pattern precedence, exclude precedence, default-allow
catalog inclusion, and unresolved-explicit fallback.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 12:49:31 +00:00
DottaandPaperclip ccf1b84c65 feat(ui): v2 Tools & Access deltas — Policies + Examples (PAP-10778)
- Policies: replace the policy cards with a real table — visible `#`
  evaluation-order column, match predicates as outline `label:value` pills
  (no more comma-soup), `DecisionBadge` effect column, and a right-aligned,
  mono `24h hits` column derived from the recent audit sample's
  `matchedPolicyIds` (footnoted as best-effort until a server counter ships).
- Examples: side-by-side two-up grid; header `smoke pass`/`smoke fail` status
  pill; inline destructive `runtime-error` banner with an intentionally
  friction-y "Install anyway" button when a smoke check trips the fails-closed
  path; footer row with "Last smoke N ago" + Install.

UI polish only. Typecheck (tsc -b) passes.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:31 +00:00
DottaandPaperclip 6215f46536 feat(ui): apply v2 Tools & Access deltas — batch 1 (PAP-10778)
Foundational + four surfaces from the PAP-10771 v2 punch list:

- EnforcementBanner: add presentational tone API (info/warning/error with
  title/body/icon slots) alongside the existing data-driven denial banner;
  showcase the tones in the design guide.
- Overview: EnforcementBanner(info) at top; MetricCards with breakdown
  sub-lines; recent denials as a real table; runtime health as PropertyRows
  + HealthBadge in a side panel.
- Runtime: EnforcementBanner(warning) with the PAP-10400 trust-tier copy
  ("local stdio is local code execution, not a security sandbox") above the
  metric grid; 4 supervisor MetricCards; slot table with a Trust tier column
  (derived client-side until the supervisor returns it); recommendations
  relocated under the metric grid, shown only when alerts fire.
- Audit: real table (time, outcome pill, mono tool, actor+run, reason, run
  link); filter bar with outcome/time-window/limit/search and a
  "server-authoritative" label.
- Applications: dense table (tinted 28x28 app icon, type pill, tool count,
  connection count, status, updated); filter bar (search, Type, Visibility);
  secondary Import manifest action.

UI polish only; trust tier and per-app tool counts derived from existing
fields/queries. Typecheck (tsc -b --force) passes.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:31 +00:00
DottaandPaperclip 460e327799 docs(mcp): add MCP Access Governance operator guide, demo script, release notes (PAP-10397)
Phase 9 / DevRel deliverable for the MCP Access Governance launch.

- doc/MCP-ACCESS-GOVERNANCE.md — canonical operator guide covering managed
  connections, catalog + risk classification, profiles and bindings, policies,
  approvals and trust rules, runtime slots, audit, local trusted deployment,
  the Paperclip-as-MCP-endpoint vs gateway explainer, and known limitations.
- doc/MCP-DEMO-SCRIPT.md — end-to-end demo for read, approval-gated write,
  and denied/destructive cases against the bundled synthetic-todo-kv fixture.
- doc/RELEASE-NOTES-mcp-access-governance.md — release notes draft with
  upgrade and verification steps. Pending CTO sign-off before publish.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:31 +00:00
DottaandPaperclip a312bbf3d2 fix(ui): address UX review for Tools & Access (PAP-10389)
- Add EnforcementBanner composite (CVA default/denied-detected) persistent
  at the top of the surface, wired to last-hour denial count; add to /design-guide.
- Add New Connection dialog: secret-reference picker (no free-text token) +
  live gateway probe before activate.
- Mobile tab nav: horizontal scroll strip instead of staggered wrap.
- Route decision/health/quarantine pills through canonical StatusBadge with
  new tool-access status keys; consolidate all tabs onto the canonical
  components/EmptyState (with description); /design-guide entries added.
- Runtime tab gets a live cyan dot when a slot is running.
- ErrorState maps 404/route-not-found to a deploy-skew friendly message.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:31 +00:00
DottaandPaperclip 1e86dd931f feat(ui): Tools & Access settings surface (Phase 6, PAP-10389)
Adds Company Settings > Tools & Access with Overview, Applications,
Connections, Profiles, Policies, Runtime, Audit, and Examples tabs wired
to the governed tool-access + gateway contracts from Phases 2-5.

- Typed API client (ui/src/api/tools.ts) for the shipped endpoints only.
- Applications: list + create. Connections: list, health-check, catalog
  refresh, tool catalog viewer. Runtime: read-only slot health (stop/
  restart disabled until control endpoints land). Audit: filterable
  gateway event timeline with run/issue links. Policies: decision
  simulator + trust-rule list/revoke. Overview: counts + recent denials.
- Profiles/Examples and runtime control/policy CRUD/transcript linkage
  show honest pending-backend notices linking follow-ups PAP-10408..10412
  rather than faking enforcement (acceptance: no UI-only enforcement).

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:31 +00:00
DottaandPaperclip 4a3400bfa3 Add MCP gateway agent eval coverage
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:01 +00:00
DottaandPaperclip b35397286f Implement governed MCP tool access
Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-06-10 12:49:01 +00:00
Dotta e2fc717294 Add MCP fixture smoke harness 2026-06-10 12:48:21 +00:00
058381349e fix(heartbeat): don't reuse runtime.sessionId across an adapter swap (#4109)
## Thinking Path

> - Paperclip orchestrates AI agents on pluggable adapters
(`claude_local`, `opencode_local`, `codex_local`, …); each adapter wraps
an external CLI.
> - The heartbeat service stores a session ID per agent and replays it
back to the adapter via `--resume` so within-task continuity is
preserved.
> - Session IDs are adapter-specific in format: claude expects a UUID,
opencode emits `ses_…`, etc. They cannot be cross-replayed.
> - When the cross-adapter session ID does slip through (operator
changes `adapterType`, edge cases in the resume path, foreign-format ID
in stored task sessions), the claude CLI hard-fails with a validation
error and every subsequent heartbeat loops on the same error until the
stored ID is manually cleared.
> - Master now ships a canonical-session-ID guard at `heartbeat.ts:8450`
(via #5972) that prevents most of this at the source, and
`isClaudePoisonedPreviousMessageIdError` recovers from the 400-class API
error.
> - This PR adds defense-in-depth at the adapter layer: the `--resume
requires a valid session ID … not a UUID …` validation error from the
claude CLI is now classified as an unknown-session signal, so the
existing fresh-session retry recovers instead of hard-failing.

## Linked Issues or Issue Description

Refs #5972 — sibling fix on the same cluster (recovers from poisoned
`previous_message_id` 400). This PR complements it by handling the
CLI-layer `--resume` validation error class.

## What Changed

- `packages/adapters/claude-local/src/server/parse.ts` — broaden
`isClaudeUnknownSessionError` regex to also match `--resume requires a
valid session`, `is not a UUID`, and `does not match any session title`.
The existing fresh-session retry at `execute.ts:612-625` now fires for
this error class.
- `packages/adapters/claude-local/src/server/parse.test.ts` — adds 4 new
test cases for `isClaudeUnknownSessionError` covering the legacy and new
patterns plus a negative case.

**Dropped from the original PR on rebase** (already on master, would
conflict):
- `server/src/services/heartbeat.ts` runtimeSessionFallback gate —
superseded by the stricter `isCanonicalSessionIdForAdapter` check on
master (#5972 lineage).
- `packages/adapters/claude-local/vitest.config.ts` and
`vitest.config.ts` projects entry — both already in master.

## Verification

```sh
pnpm --filter @paperclipai/adapter-claude-local vitest run
# 19/19 passed (3 files, includes 4 new isClaudeUnknownSessionError cases)
```

Pre-existing failure on
`server/src/__tests__/heartbeat-process-recovery.test.ts > queues
exactly one retry when the recorded local pid is dead` reproduces on
`origin/master` — unrelated to this PR.

## Risks

- **Low-to-medium.** The added regex fragments are narrow. `--resume
requires a valid session` and `does not match any session title` are
unambiguously session-related. `is not a UUID` is more generic; worst
case is one extra retry on an unrelated CLI validation error that would
also fail on the same root issue. Happy to drop `is not a UUID` if
reviewers prefer.
- **No DB migration; no schema change; no behavior change when adapter
types match (the common path).**

## Model Used

- Provider: Anthropic (Claude)
- Model: `claude-opus-4-7` (Opus 4.7), 1M context window
- Tool: Claude Code CLI with extended thinking + tool use; human review
on the rebase and the regex narrowing tradeoffs

## Checklist

- [x] I searched the GitHub PR list for similar PRs and confirmed this
is not a duplicate (related: #5972 already merged, complementary scope)
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass (19/19 claude-local)
- [x] I have added or updated tests where applicable
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Devin Foley <devin@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>
canary/v2026.610.0-canary.4
2026-06-09 21:13:20 -07:00
0713dfa41f fix: validate session ID as UUID before --resume + error diagnostics (DLD-889) (#1742)
## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - The Claude-local adapter uses `claude --resume <session-id>` to
continue prior sessions; the `--resume` value MUST be a UUID per
Claude's CLI contract.
> - Paperclip internally uses session IDs prefixed with `ses_` (not
UUIDs); these get passed straight through to `--resume` and crash the
run.
> - On top of the crash, when the underlying error path triggers a
secret-decryption failure or heartbeat setup failure, the diagnostics
are too thin to tell key-mismatch from other failures, and the heartbeat
error code is mis-classified as `adapter_failed` instead of
`setup_failed`.
> - This PR validates `runtimeSessionId` against a UUID regex before
letting `canResumeSession` become true, adds `not a valid UUID` to
Claude's own retry-error regex, improves AES-256-GCM decryption
diagnostics in the local encrypted provider, and re-classifies
pre-adapter setup failures.
> - The benefit is that Paperclip session IDs are detected and skipped
gracefully (logged, no crash), legitimate Claude UUID-rejection errors
are treated as retriable, and operators can diagnose decryption/setup
failures from the run log.

## Linked Issues or Issue Description

**What happened?**

The `claude-local` adapter passes Paperclip's internal session
identifiers (e.g. `ses_…`) straight to `claude --resume <session-id>`.
Because Claude's CLI requires the `--resume` argument to be a UUID, the
run crashes with a `not a valid UUID` error. When the surrounding code
path also hits a secret-decryption failure, the heartbeat reports it as
`adapter_failed`, hiding the real `setup_failed` cause and making
diagnosis hard.

**Expected behavior**

Non-UUID session IDs should be detected before `--resume` is called, the
run should fall back to a fresh session with a clear log line, and any
decryption / setup failure should be reported with enough detail (and
the correct error code) for an operator to tell what failed.

**Steps to reproduce**

1. Have a persisted task session whose ID is not a UUID
(Paperclip-issued `ses_…` form).
2. Trigger a heartbeat that resumes that session via the `claude-local`
adapter.
3. Observe: the adapter crashes with a UUID-validation error; if the
path also involves a decryption failure, the heartbeat surfaces
`adapter_failed` instead of `setup_failed`.

## What Changed

- `packages/adapters/claude-local/src/server/execute.ts`: Validates
`runtimeSessionId` against a UUID regex before setting
`canResumeSession`; non-UUID IDs are logged and skipped gracefully.
Guards the cwd-mismatch log block on `isValidUuid` so it does not fire
for non-UUID session IDs.
- `packages/adapters/claude-local/src/server/parse.ts`: Adds `not a
valid UUID` to the session-error retry regex so Claude's own UUID
rejection is treated as a retriable error.
- `server/src/services/secrets/local-encrypted-provider.ts`: Wraps
AES-256-GCM decryption in try/catch and re-throws with a key fingerprint
hint to aid key-mismatch diagnosis.
- `server/src/services/heartbeat.ts`: Corrects the outer-catch
`errorCode` from `adapter_failed` to `setup_failed` for pre-adapter
setup failures.
- `AGENTS.md`: Adds task/PR/CI governance sections (10–13) and expands
the Definition of Done.

## Verification

- `pnpm --filter @paperclipai/adapter-claude-local test` covers UUID
validation and the parse retry regex.
- `pnpm --filter @paperclipai/server test src/services/secrets` covers
decryption diagnostics.
- `pnpm --filter @paperclipai/server typecheck`

## Risks

Low. UUID validation is strictly additive (non-UUIDs that previously
crashed now log and skip). Decryption diagnostics only fire on failure
paths. The `setup_failed` error code change is a clearer classification,
not a behavior change.

## Model Used

Claude (Opus 4.6) — used to identify the UUID-validation root cause,
mirror existing parse patterns, and re-classify the heartbeat setup
error code.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots (N/A — no UI changes)
- [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 (in progress)
- [ ] 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: CTO Agent <cto@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Devin Foley <devin@paperclip.ing>
canary/v2026.610.0-canary.3
2026-06-09 20:21:10 -07:00
67b22d872f [codex] Clarify interrupt handoffs and scoped wake semantics (#7855)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The issue thread is the operator surface where comments, assignee
changes, pauses, resumes, and wakeups turn human intent into agent
execution.
> - Interrupting a live run and handing work to another assignee needs
clear semantics so the product does not accidentally keep work alive,
wake the wrong participant, or hide why an agent stopped.
> - Comment-driven wakes also need strict boundaries so closed, blocked,
and dependency-driven work only resumes when there is real actionable
input.
> - This pull request codifies the interrupt handoff contract,
implements backend scheduling behavior, and gives the UI clearer
handoff/pause language.
> - The benefit is a more inspectable and predictable task lifecycle for
both operators and agents.

## Linked Issues or Issue Description

Paperclip issue: `PAP-10664` / `PAP-10751`.

Problem: interrupting or reassigning live agent work could be ambiguous
in the UI and backend. Operators needed clearer feedback about whether a
handoff wakes an agent, what pause/cancel affects, and when comments
should revive execution. The backend also needed stronger tests around
comment wake boundaries, retry supersession, and structured agent
mention dispatch.

Related GitHub PR search found broad workflow-adjacent PRs #5082, #6359,
and #4083, but no exact duplicate for this head branch or
interrupt-handoff scope.

## What Changed

- Added an interrupt handoff semantics document covering destination
behavior, wake expectations, and live-run interruption states.
- Implemented backend interrupt handoff behavior and comment wake/reopen
handling in issue routes/services and heartbeat scheduling.
- Hardened structured agent mention dispatch so mentions resolve through
the intended dispatch path.
- Added UI helpers and components for handoff chips, wake rows,
interrupt banners, pause-affects summaries, and composer guidance.
- Updated the issue properties assignee picker and issue chat/composer
surfaces to make interrupt/reassign behavior clearer.
- Added backend, UI utility, component, and Storybook coverage for the
new behavior.
- Stabilized the new UI component tests with a local `flushSync`-backed
act helper matching existing repo practice in this dependency set.
- Addressed Greptile feedback by threading historical run `errorCode`
through issue-run data and operator-interrupted chat labels.
- Addressed Greptile's cancel ordering concern by terminating/deleting
in-memory heartbeat processes before cancellation status persistence,
with regression coverage for DB update failure.

## Verification

- `git diff --check $(git merge-base HEAD origin/master)..HEAD`
- `pnpm --filter @paperclipai/ui exec vitest run
src/lib/interrupt-handoff.test.ts src/lib/issue-chat-messages.test.ts
src/components/IssueProperties.test.tsx
src/components/interrupt-handoff/InterruptHandoffViews.test.tsx
--no-file-parallelism --maxWorkers=1` — 4 files / 91 tests passed before
the Greptile follow-ups.
- `pnpm run preflight:workspace-links && pnpm exec vitest run
server/src/__tests__/heartbeat-process-recovery.test.ts
server/src/__tests__/heartbeat-retry-scheduling.test.ts
server/src/__tests__/issue-comment-reopen-routes.test.ts
server/src/__tests__/issue-tree-control-service.test.ts
server/src/__tests__/issue-update-comment-wakeup-routes.test.ts
server/src/__tests__/issues-service.test.ts --no-file-parallelism
--maxWorkers=1` — 6 files / 191 tests passed before the Greptile
follow-ups.
- `pnpm --filter @paperclipai/ui exec vitest run
src/lib/issue-chat-messages.test.ts --no-file-parallelism
--maxWorkers=1` — 1 file / 24 tests passed after the historical
`errorCode` follow-up.
- `pnpm exec vitest run server/src/__tests__/activity-service.test.ts
server/src/__tests__/activity-routes.test.ts --no-file-parallelism
--maxWorkers=1` — 2 files / 11 tests passed after the historical
`errorCode` follow-up.
- `pnpm exec vitest run
server/src/__tests__/heartbeat-process-recovery.test.ts
--no-file-parallelism --maxWorkers=1` — 1 file / 52 tests passed after
the cancel ordering follow-up.
- Greptile is green for head `272647636287d034bab8d981eaf5305865aa0f96`;
the old inline P2 is resolved/outdated.
- GitHub Actions, Socket, security-review, and Greptile checks are green
for head `272647636287d034bab8d981eaf5305865aa0f96`. The external
`security/snyk (cryppadotta)` status was still pending at
`https://app.snyk.io/org/cryppadotta/pr-checks/85b3e8f4-04e1-4f8e-9362-899c8148c23c`
after a bounded wait.

## Risks

- Medium: changes touch issue comments, wake scheduling, and live-run
interruption semantics, so regressions could affect when agents resume
or stay stopped.
- Medium: UI copy and state grouping for assignee changes may need
reviewer tuning after product review.
- Low migration risk: no database schema migration is included.
- The branch was created before the latest `origin/master` commits;
reviewers should confirm CI merge-base behavior and resolve any merge
conflicts if GitHub reports them.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

OpenAI Codex, GPT-5-based coding agent, tool use and local command
execution enabled. Exact hosted model build and context window were not
exposed by the runtime.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] 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

Screenshot note: this PR includes Storybook coverage for the new
interrupt handoff UI states rather than captured before/after browser
screenshots in this PR-creation heartbeat.

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
canary/v2026.610.0-canary.2
2026-06-09 21:57:21 -05:00
xiduiandDevin Foley 5d315ab778 Defer same-issue forceFreshSession wakes into follow-up runs (#4080)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The heartbeat service governs how agent wake events get queued,
deferred, or folded into the currently-running adapter run
> - `forceFreshSession: true` wakes on a same-agent/same-issue path get
silently folded into the active run, so callers can never request a true
cold-start follow-up
> - This breaks phased workflows that need to drop a poisoned session
and restart cleanly on the same issue without bouncing to another agent
> - This PR extracts the existing same-issue follow-up decision into
`shouldDeferFollowupWakeForSameIssue` and extends it to also defer
`forceFreshSession: true` wakes into a follow-up run boundary
> - The benefit is that `forceFreshSession` now behaves as documented:
it actually starts a fresh session, even when the wake targets the same
agent/issue/runtime that is currently executing

## Linked Issues or Issue Description

**What happened?**

A wake event posted with `forceFreshSession: true` against an issue
whose current adapter run is still `running` on the same execution agent
is silently coalesced into that in-flight run instead of starting a cold
session. Callers that explicitly request a fresh-session reset see no
behavior change until the run naturally completes.

**Expected behavior**

`forceFreshSession: true` should always force a fresh session start,
even when the wake targets the same agent/issue that is currently
executing. The wake should defer into a follow-up run boundary if the
current run is still in-flight.

**Steps to reproduce**

1. Start an adapter run for some issue.
2. While the run is still `running`, post a wake event for the same
issue/agent with `forceFreshSession: true`.
3. Observe: the active run continues without resetting the session; the
fresh-session signal is dropped.

## What Changed

- Extracted same-issue follow-up decision into exported helper
`shouldDeferFollowupWakeForSameIssue` in
`server/src/services/heartbeat.ts`
- Extended that helper so `forceFreshSession: true` (not only
`wakeCommentId`) defers into a follow-up run when the current run is
still `running` for the same execution agent
- Added stickiness to `mergeCoalescedContextSnapshot`: if either side of
a wake-merge has `forceFreshSession: true`, the merged snapshot keeps it
set so it is not silently dropped while queued wakes coalesce
- Added five unit tests in `heartbeat-workspace-session.test.ts`
covering each decision branch of the helper

## Verification

- `pnpm --filter @paperclipai/server test
src/__tests__/heartbeat-workspace-session.test.ts`
- `pnpm --filter @paperclipai/server typecheck`

## Risks

Low. Behavior change only affects the narrow case where a
same-agent/same-issue wake carries `forceFreshSession: true` while the
active run is still `running`. Other wake paths (cross-agent,
queued/failed runs) are untouched. The helper extraction is a pure
refactor preserving the prior comment-wake deferral.

## Model Used

Claude (Opus 4.7) — extended thinking enabled, used to extract the
helper, extend the deferral condition to cover `forceFreshSession`, and
write unit coverage.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots (N/A — no UI changes)
- [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 (in progress)
- [ ] 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: Devin Foley <devin@paperclip.ing>
canary/v2026.610.0-canary.1
2026-06-09 17:09:02 -07:00
DottaandClaude Opus 4.8 fae7e920a9 [codex] Polish routine layout follow-ups (#7858)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Routines are the recurring-work surface that lets a company keep
operating without a human manually kicking off every task
> - The base routine detail Variation C shell already landed in #7848,
but the follow-up branch still had polish work for scheduling, section
ergonomics, and the list layout
> - Operators need routine edit screens to explain trigger behavior
clearly, keep long detail pages usable on mobile/touch devices, and make
grouped routine lists easier to scan
> - This pull request rebases the remaining branch work onto current
`master`, drops the duplicate commits already merged through #7848, and
keeps only the new routine UI follow-ups
> - The benefit is a cleaner routines workflow without reopening the
already-merged shell work or carrying unrelated lockfile, workflow, or
screenshot changes

## Linked Issues or Issue Description

Refs #7848

Feature follow-up: polish the routines UI after the Variation C
routine-detail shell landed.

Problem / motivation:

- Routine trigger configuration needs clearer previews for manual,
schedule, API, and webhook execution modes.
- Routine detail sections need better responsive spacing and touch
ergonomics.
- The routines list grouping should scan like grouped records instead of
a table with heavy row dividers.
- The routine tests need a React 19-compatible render helper so the
focused routine suite can run in this workspace.

Proposed solution:

- Add cron-fire preview helpers and routine-run display helpers with
focused tests.
- Expand the routine editable and operate sections with richer trigger,
variable, run, activity, and history presentation.
- Adjust the routine detail shell and sub-sidebar spacing for
mobile/touch layout.
- Update grouped routine list presentation to use bordered group headers
with borderless rows.
- Switch affected routine tests to the repo's `flushSync` render-helper
pattern.

Alternatives considered:

- Leaving the duplicate pre-#7848 commits in the branch would recreate
conflicts and make the PR review much larger than the remaining change.
- Keeping grouped routine rows inside one bordered table was simpler,
but made the grouping hierarchy less legible.

Roadmap alignment:

- ROADMAP.md lists Scheduled Routines as a core shipped capability and
Output/Enforced Outcomes as ongoing priorities. This is polish on that
existing routines capability, not a new roadmap-level feature.

## What Changed

- Added routine scheduling preview helpers and tests for
cron/manual/API/webhook fire-policy display.
- Added routine run display helpers and tests for deduped trigger labels
and run-row subtitles.
- Polished routine detail sections, including trigger summaries, operate
views, and env/variable editing ergonomics.
- Adjusted routine detail page and sub-sidebar spacing so the
title/header area is less pinned and touch layouts center better.
- Reworked the routines list grouped layout so group headers are
bordered cards and routine rows are borderless inside each group.
- Added Storybook coverage for the routines list grouped layout and
updated the existing routine detail story.
- Repaired routine tests to use `flushSync` helpers compatible with the
installed React 19 runtime.

## Verification

- `pnpm exec vitest run ui/src/lib/cron-fires.test.ts
ui/src/lib/routine-run-display.test.ts ui/src/pages/Routines.test.tsx
ui/src/components/RoutineSubSidebar.test.tsx
ui/src/components/RoutineSaveBar.test.tsx`
  - Result: 5 test files passed, 37 tests passed.
- Confirmed the rebased PR diff does not include `pnpm-lock.yaml`,
`.github/workflows/*`, or committed screenshots.
- Confirmed `origin/master` is an ancestor of the pushed branch head
after rebase.

## Risks

- Medium UI risk: this touches the routine detail and routine list
surfaces, so visual regressions are possible in edge cases not covered
by the focused tests.
- Low data risk: no schema, migration, server API, or lockfile changes
are included.
- Review note: the branch intentionally force-pushed after rebasing
because the original first three commits were already merged through
#7848.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

OpenAI Codex, GPT-5-based coding agent runtime, with repository
shell/tool access. Exact hosted runtime model identifier and
context-window size were not exposed in the execution environment.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-09 18:55:01 -05:00
e3aada1df2 feat(ui): add Feedback item to the account flyout menu (PAP-107) (#7854)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The web UI has a bottom-left account flyout menu where users reach
profile, docs, and the light/dark toggle
> - There was no in-product way for users to send feedback or report
issues — they had to find an external channel
> - We want a low-friction, always-visible entry point for feedback, and
a clean URL we can re-point later without shipping app changes
> - This pull request adds a **Feedback** item (Megaphone icon) to the
account flyout, between Documentation and the theme toggle, that opens
`https://paperclip.ing/feedback` in a new tab
> - `paperclip.ing/feedback` is a stable indirection (added to the
marketing site) that currently 302-redirects to a Google Form, so the
destination can be swapped for a richer solution later with no app
release
> - The benefit is a one-click feedback path for users and a
future-proof link the team controls

## Linked Issues or Issue Description

No public GitHub issue exists (tracked internally as Paperclip PAP-107).
Describing the underlying request inline as a feature, per
CONTRIBUTING.md path (B):

### Problem or motivation

Users have no in-app affordance to give feedback or report issues; that
friction loses signal we'd otherwise act on.

### Proposed solution

Add a Feedback item to the account flyout (Megaphone icon, between
Documentation and the theme toggle) that opens a stable
`paperclip.ing/feedback` URL in a new tab. That URL redirects to a
Google Form for now, keeping the client decoupled from the destination.

### Alternatives considered

Linking the Google Form directly from the app — rejected because it
bakes a throwaway URL into the client; the `/feedback` indirection keeps
the link clean and swappable.

### Roadmap alignment

Small, self-contained UX addition; no overlap with planned core work
(checked ROADMAP.md). The `/feedback` redirect lives in the separate
`paperclip-website` repo (Astro site on Cloudflare Pages), commit
`f65b566`. No duplicate/related PRs found in this repo (searched
feedback/flyout/menu).

## What Changed

- `ui/src/components/SidebarAccountMenu.tsx`: import `Megaphone` from
`lucide-react`; add `FEEDBACK_URL = "https://paperclip.ing/feedback"`
const next to `DOCS_URL`; insert a `Feedback` `MenuAction` between
Documentation and the theme toggle using the `external` prop so it opens
in a new tab (`target="_blank"`, `rel="noreferrer"`) and closes the
popover on click.
- `ui/src/components/SidebarAccountMenu.test.tsx`: assert the Feedback
item renders with the correct `href`, opens in a new tab, and is ordered
after Documentation and before the theme toggle.
- (Separate repo, for context) `paperclip-website` `public/_redirects`:
`/feedback` → 302 → the feedback Google Form.

## Verification

- **Unit tests:** `SidebarAccountMenu` tests pass (item renders, correct
`href`, `target="_blank"`, ordering). Run: `cd ui && npm test --
SidebarAccountMenu`.
- **Manual / canary:** The board previewed the canary build of the menu
item and accepted it. Clicking **Feedback** opens a new tab to
`paperclip.ing/feedback`.
- **Redirect:** After the Cloudflare Pages deploy propagates, `curl -sI
https://paperclip.ing/feedback` returns the Google Form in the
`Location` header.

_Screenshots:_ UI change was validated via the accepted canary preview;
the item reuses the existing `MenuAction` styling, so it visually
matches the Documentation/theme rows.

## Risks

- **Low risk.** Additive, self-contained UI change with no new state or
API calls. The only external dependency is the `paperclip.ing/feedback`
redirect (separate repo, already deployed); if it were missing the link
would 404, but it is in place. No migrations, no breaking changes.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR.

## Model Used

- **Claude (Anthropic).** PR authoring/orchestration:
**claude-opus-4-8** (extended thinking + tool use). The implementation
commit `b454a12d` was produced with assistance from
**claude-sonnet-4-6**. All changes reviewed before pushing.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
canary/v2026.610.0-canary.0
2026-06-09 16:42:15 -07:00
8ee3987d12 adapter-claude-local: recover from poisoned previous_message_id 400 (detect + clearSession) (#5972)
## Thinking Path

> - Paperclip's `claude_local` adapter persists Claude Code session
jsonls under `~/.claude/projects/…/{sessionId}.jsonl` and resumes them
on the next heartbeat
> - When Claude Code injects `<synthetic>` placeholder assistant
messages (after rate-limit, max-turn exhaustion, or transient-upstream
failures) those placeholders get UUID-format `message.id`s rather than
`msg_…`-format ids
> - On the next `--resume`, Claude Code passes that UUID as
`previous_message_id` and Anthropic's API rejects it with a 400:
``diagnostics.previous_message_id: must be the `id` from a prior
/v1/messages response (starts with `msg_`)``
> - The adapter had a session-rotation fallback only for "unknown
session" errors, so the poisoned session was `--resume`-d indefinitely
and the agent flipped between `idle` and `error` every heartbeat
> - Even worse, the *result* event of the failing run still carried a
`session_id`, and the adapter was persisting that id into the
issue-scoped session store (`agentTaskSessions`). So even after we
detected the 400, every subsequent continuation re-loaded the same
poisoned id and hit the same 400 again — the issue was permanently
stranded
> - We observed this on multiple agents in our deployment; the only
manual fix was to rename the `.jsonl`, which is not a viable long-term
workaround
> - This PR detects the 400, runs the same session-rotation fallback the
unknown-session path uses **and** stops persisting the poisoned id, so
the next attempt starts genuinely fresh

## Linked Issues or Issue Description

No external GitHub issue is linked. Describing the problem inline
following the bug-report template:

**What happened:** `claude_local` agents flipped between `idle` and
`error` on every heartbeat because the persisted session jsonl carried a
synthetic UUID `previous_message_id` (from `<synthetic>` assistant
placeholders injected after rate-limit/max-turn/upstream errors).
Anthropic's API rejected every `--resume` with a 400:
``diagnostics.previous_message_id: must be the `id` from a prior
/v1/messages response (starts with `msg_`)``.

**Expected behavior:** When the persisted session is poisoned and
unrecoverable, the adapter should rotate to a fresh session — the same
fallback path already used for unknown-session errors — and stop
re-persisting the poisoned `session_id`.

**Actual behavior:** The session-rotation fallback only matched the
"unknown session" pattern, so the poisoned session was `--resume`-d
forever. The result event of the failing run still carried `session_id`,
which was being persisted into `agentTaskSessions`, so every subsequent
continuation reloaded the same poisoned id and hit the same 400.

**Reproduction:** Inject any flow that causes Claude Code to emit a
`<synthetic>` placeholder (rate-limit, max-turn exhaustion, transient
upstream failure). The next `--resume` will fail with the 400 and the
agent will not self-recover.

**Scope of fix:** Add a `previous_message_id` 400 detector; route it
through the existing unknown-session fallback; drop the poisoned
`sessionId` and emit `clearSession: true` so the heartbeat service wipes
the persisted row; best-effort delete the local poisoned `.jsonl`.

## What Changed

Two commits:

1. **`adapter-claude-local: auto-rotate session on previous_message_id
400 (synthetic-msg poisoning)`** — detector + execute-time rotation
2. **`adapter-claude-local: guard against persisting poisoned
sessionId`** — validate-before-persist + `clearSession`

Combined diff:

- `parse.ts`: new `isClaudePoisonedPreviousMessageIdError(parsed)`
matching ``/diagnostics\.previous_message_id.*starts with `msg_`/i``
against `parsed.result` and `extractClaudeErrorMessages(parsed)`
- `parse.ts`: `isClaudeTransientUpstreamError()` excludes the new error
from transient classification so it isn't masked as retryable upstream
noise
- `execute.ts`: expand the resume-fallback branch so it triggers on both
`isClaudeUnknownSessionError` and the new
`isClaudePoisonedPreviousMessageIdError`, with a distinct log line
(`"returned a poisoned message-id"` vs `"is unavailable"`)
- `execute.ts`: for local (non-remote) execution targets, best-effort
delete the poisoned `~/.claude/projects/.../{sessionId}.jsonl` before
retrying so the file can't be accidentally resumed by an out-of-band
caller. The `fs.unlink` and follow-up log call are in separate try/catch
blocks so a closed log stream cannot mask a successful unlink (and vice
versa)
- `execute.ts` / `toAdapterResult`: when a result carries the poisoned
400, **drop** `sessionId`/`sessionParams`/`sessionDisplayId` (return
`null`) and emit `clearSession: true` so the heartbeat service's
`resolveNextSessionState` wipes the persisted row. The result also
surfaces `errorCode: "claude_poisoned_previous_message_id"` for
observability
- `docs/adapters/claude-local.md`: runbook entry — symptom,
auto-recovery flow, on-call checklist
- Tests:
- 4 new `parse.test.ts` cases covering positive detection in `result`
and `errors[]`, negative cases, and non-transient classification
- 3 new `claude-local-execute.test.ts` cases: (a) fresh run reports the
poisoned error → sessionId dropped + `clearSession: true`; (b) recovery
retry also reports the poisoned error → same guards apply; (c)
session-rotation success on retry

## Verification

```bash
pnpm --filter @paperclipai/adapter-claude-local exec vitest run src/server/parse.test.ts
pnpm --filter @paperclipai/server exec vitest run src/__tests__/claude-local-execute.test.ts
```

Both suites green locally. This patch is also currently running as a
hot-patch over the published `2026.513.0` adapter on the reporting
deployment — sessions that previously looped indefinitely now
self-recover on the first heartbeat after the 400 surfaces.

## Risks

- Low risk. The detector is conservative (regex over `result` +
`errors[]` only) and the rotation reuses the existing unknown-session
fallback path
- The local-only `fs.unlink` of the poisoned `.jsonl` is wrapped in
`try/catch` and ignored on failure — strictly an optimization; the
server-side session clear is the authoritative reset
- Remote execution targets (`executionTargetIsRemote`) skip the disk
cleanup because the file lives on a remote host that we can't safely
reach from the adapter
- The `clearSession: true` + nulled session fields path is a no-op on
healthy runs; it only fires when the new detector matches, so existing
successful continuations are unaffected
- No DB schema changes, no public API changes, no new dependencies

## Model Used

- Provider: Anthropic Claude
- Model: `claude-opus-4-7` (Opus 4.7)
- Context window: 1M
- Capabilities: extended reasoning, tool use, code execution
- Role: implemented the detector, expanded the fallback branch, added
the persist-guard + `clearSession`, wrote the unit + integration tests,
validated locally, and applied the equivalent hot-patch to the deployed
`2026.513.0` install while this PR is in review

## 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 similar or duplicate PRs and linked
them — closed #2295, #2361, #3572, #5438 as duplicates of this canonical
fix; complementary fixes #4838 (heartbeat_timer reset) and #4932 (gemini
context-overflow rotation) target different code paths
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots — N/A, adapter-only change
- [x] I have updated relevant documentation
(`docs/adapters/claude-local.md` runbook entry)
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Danial Jawaid <danial.jawaid@gmail.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Devin Foley <devin@paperclip.ing>
canary/v2026.609.1-canary.2
2026-06-09 15:45:47 -07:00