Addresses UXDesigner review against the approved design spec:
- Placement: move the discovery affordance into a calm action row at the
bottom of IssueWorkspaceCard ("Browse files…" + "Open file by path…"),
removing the orphaned button between Artifacts and Tabs. The existing
top-right toolbar / `g f` entry stays as the secondary affordance.
- Single sheet, two modes: opening a result from browse now shows a
"← Back to files" affordance (and a separate × close) in the view header,
with Esc returning to the list. Browse state is URL-backed (`browse=1`,
`q`) via FileViewerContext (open(...{fromBrowse}), openBrowse, backToFiles).
- Remove the Recent/All toggle: empty query → Recently changed (silent
fallback to full listing when git change-tracking is unavailable);
populated query → Files matching. Search field accepts `path:line` and
Enter opens the highlighted row or the typed path.
- Mobile (<sm) two-line rows (basename / dirname, no timestamp, 44px tap
targets); desktop single-line with dir-truncate. Recently-changed shows
relative timestamps; search results omit them to maximise path width.
- Keyboard: listbox/option roles, ↑/↓ + Enter, aria-activedescendant,
combobox search field.
- Align unavailable copy with describeDenial (remote / cleaned-up);
debounce 150ms; documented the 100-row cap.
- Stories now render the real FileViewerSheet / IssueWorkspaceCard for
truthful light+dark, desktop+360px, view-mode, and placement captures.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Adds a discoverable "Browse workspace" control near the issue output/
artifacts area that opens the existing FileViewerSheet. The sheet's empty
state now hosts a WorkspaceFileBrowser: debounced path/name search, a
workspace selector (auto/execution/project) and a recent-changes/all
toggle, backed by the GET /file-resources/list API. Rows show the
workspace label, file kind and size with long-path-safe truncation
(directory truncates, basename stays visible), and clicking a file opens
the viewer via a URL-backed deep link. Distinct calm states cover no
workspace, remote workspace, cleaned-up workspace, and recent-changes
unavailable, plus transport/denied errors.
- WorkspaceFileBrowser component + describeUnavailable reason mapping
- Integrate into FileViewerSheet empty state with manual-path fallback
- "Browse workspace" affordance on the issue page
- Unit tests for list/states/open + Storybook stories for review
Co-Authored-By: Paperclip <noreply@paperclip.ing>
- Remove pill chrome from workspace/type/size/line meta row; use
bulleted plain text so it reads as metadata, not status chips.
- Give line-number gutter a dedicated 16px right pad so numbers stop
butting up against code.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Reject ASCII control characters in workspaceFileResourceQuerySchema and
translate that ZodError to the existing 422 + {code: "invalid_path"} shape
in the route layer. The old service-level null-byte check still fires, but
now we reject at the boundary before audit logging tries to write the raw
path into Postgres JSONB (the true source of the 500).
- Parse path:line[:col] in OpenFilePrompt.handleSubmit via parseWorkspaceFileRef,
matching what inline WorkspaceFileLinks and URL deep-links already do, and
widen onSubmit/handlePromptSubmit to carry line/column through to viewer.open.
- Add a regression test for the control-character rejection. Fix a pre-existing
bug in file-resources.test.ts (missing await + wrong field names on the
embedded-postgres helper) so the DB-backed tests actually run instead of
silently skipping.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Addresses UX review feedback on PAP-1963:
- Fix denial-body leak for too_large/size codes (describeDenial no longer
echoes fallback for known codes; the call site passes empty fallback so
unknown codes show a generic message).
- Sticky line-number gutter with solid code-bg fill; highlight border
moves from absolute-positioned sibling onto the sticky gutter so the
amber marker stays pinned when users scroll long lines horizontally.
- Swap FileSearch copy-link icon for Link2.
- WorkspaceFileLink now sets a real deep-link href so modifier-click
opens the file viewer in a new tab instead of scrolling to the top.
- Collapse duplicate title/description in the sheet header when the
basename equals the full path (e.g. .env.production).
- Drop the duplicate title/helper block from OpenFilePrompt (sheet
header already carries the title + description).
- Replace ArrowLeft with Cloud for the remote-workspace state.
- Retire arbitrary text-[12.5px]/[11px]/[0.78em] sizes in favor of text-xs.
- Unify 404 copy on "active workspace" everywhere.
- Raise chip-row contrast by using bg-muted instead of bg-background.
Also commits previously untracked visual-regression infra:
- Storybook stories for 12 file viewer states
- screenshot-file-viewer.mjs / screenshot-one.mjs
- describeDenial unit tests
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Adds the Phase 3 UI for the workspace file viewer:
- FileViewerProvider/FileViewerSheet pair, URL-addressable via
?file=/?line=/?column=/?workspace= so browser back closes or
walks back through sheet history.
- Remark plugin + parser that only auto-link path refs inside
inline code spans (requires a slash or a line anchor to avoid
prose matches like README.md).
- Shared WorkspaceFileLink primitive used by markdown output; same
primitive will be reusable for run output and work-product chips.
- Issue toolbar "Open file" action, Command Palette entry
"Open file in this issue...", and the `g f` keyboard route.
- Designed state views for not found / outside workspace / denied /
too large / binary / remote-only / workspace-archived / loading
progressive states, with polite live-region announcements and a
keyboard-scrollable code viewport.
Tests cover the parser, the remark plugin, URL state reading/writing,
the keyboard shortcut, and markdown-body workspace link rendering.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - Each agent is woken via the heartbeat scheduler — `heartbeat_timer`
for periodic interval wakes, `issue_assigned` / `execution_*` /
`issue_commented` for event-driven wakes
> - The heartbeat reuses the prior task session by default; only
specific wake reasons trigger a fresh session via
`shouldResetTaskSessionForWake` (assignment, review, approval,
changes-requested) or explicit `forceFreshSession`
> - In CEO run `292a5fd1`, repeated context compaction warnings appeared
near the 64k threshold for the long-lived manager session — symptomatic
of repeated `heartbeat_timer` wakes accumulating low-value "checked,
nothing new" inbox-scan traces inside one ever-growing session
> - PF-4 in the 2026-04-16 hangeul-school operational issue set asks for
a compaction-aware session freshness policy: "manager sessions can
rotate before low-value compaction pressure accumulates" and "repeated
timer wakes do not indefinitely bloat the same session"
> - This pull request adds `wakeReason === "heartbeat_timer"` to both
`shouldResetTaskSessionForWake` and `describeSessionResetReason`, so
each interval wake starts fresh and the run log explicitly records why.
Event-driven wakes (`issue_commented`, `transient_failure_retry`, etc.)
keep their existing reuse behavior.
> - The benefit is that timer wakes — which are exploratory and carry no
continuation state — stop bloating long-lived manager sessions.
Compaction pressure that previously accumulated across N timer wakes is
now bounded to a single interval's worth of context.
## Linked Issues or Issue Description
No external GitHub issue is linked. Describing the problem inline
following the bug-report template:
**What happened:** Long-lived manager/CEO agent sessions hit the 64k
context-compaction threshold after many `heartbeat_timer` wakes
accumulated low-value inbox-scan traces inside one ever-growing task
session. Reproduced in CEO run `292a5fd1`.
**Expected behavior:** Periodic timer wakes — which carry no
continuation state — should not indefinitely bloat the same session. The
heartbeat should rotate sessions on timer wakes the way it already does
on assignment/review/approval/changes-requested wakes.
**Actual behavior:** `shouldResetTaskSessionForWake` only reset on
`issue_assigned`, `execution_review_requested`,
`execution_approval_requested`, `execution_changes_requested`, or
explicit `forceFreshSession`. `heartbeat_timer` reused the prior session
indefinitely, causing compaction pressure.
**Scope of fix:** Add `heartbeat_timer` to the reset list and to
`describeSessionResetReason` so the run log records why. Event-driven
wakes keep their existing reuse behavior.
## What Changed
- `shouldResetTaskSessionForWake` (`server/src/services/heartbeat.ts`)
now also returns `true` when `wakeReason === "heartbeat_timer"`. The
existing reset reasons (`issue_assigned`, `execution_review_requested`,
`execution_approval_requested`, `execution_changes_requested`,
`forceFreshSession`) are unchanged.
- `describeSessionResetReason` returns a paired explanation `"wake
reason is heartbeat_timer (timer-driven wake starts fresh)"` so run logs
make session reset behavior legible.
- `describeSessionResetReason` was promoted from internal to `export` so
the paired contract can be unit-tested directly alongside
`shouldResetTaskSessionForWake`. This is the only API surface change in
this PR.
Wake reasons whose reuse behavior is intentionally **unchanged**:
- `issue_commented` — the comment is the reason to engage; continuation
context matters
- `issue_comment_mentioned` — same rationale
- `transient_failure_retry` — resuming a previously-failed run; want
continuity
- `process_lost_retry` — resuming after process loss; want continuity
- `missing_issue_comment`, recovery reasons — out of scope; can be
revisited as follow-ups if observed bloat shows up
## Verification
```bash
cd server
pnpm vitest run src/__tests__/heartbeat-timer-wake-session-reset-pf4.test.ts
# 12/12 pass
pnpm vitest run \
src/__tests__/heartbeat-stale-queue-invalidation.test.ts \
src/__tests__/heartbeat-process-recovery.test.ts \
src/__tests__/heartbeat-comment-wake-batching.test.ts
# 48/48 adjacent heartbeat tests pass
```
The 12 new tests assert:
1. `shouldResetTaskSessionForWake` resets on `heartbeat_timer`
2. `shouldResetTaskSessionForWake` still resets on the four existing
reasons
3. `forceFreshSession === true` still triggers reset
4. `issue_commented`, `transient_failure_retry`, unknown reasons, and
null/undefined context do **not** trigger reset
5. `describeSessionResetReason` describes `heartbeat_timer` explicitly
so logs are legible
6. `describeSessionResetReason` keeps the exact wording for the four
existing reasons
7. `describeSessionResetReason` returns the `forceFreshSession` message
8. `describeSessionResetReason` returns `null` for non-resetting reasons
9. **Parity invariant**: the two functions agree on every input —
`describeSessionResetReason(ctx)` is non-null iff
`shouldResetTaskSessionForWake(ctx)` returns true. This locks the pair
so future changes to one must update the other.
## Risks
- **Low–medium.** This changes behavior for every `heartbeat_timer` wake
on every agent: the prior task session is no longer reused.
- For **manager / CEO agents** (the documented case): this is the
intended improvement. Timer wakes carry no continuation state for these
roles.
- For **worker agents** that may have used timer wakes to resume
in-flight work: any genuine continuation should already be triggered by
issue/execution wake reasons (which still reuse) or by an active
checkout being resumed via `process_lost_retry` /
`transient_failure_retry`. Timer wakes themselves do not create
checkouts.
- If a deployment relied on timer wakes to preserve mid-task context —
which is fragile by design — the right path is to switch to a non-timer
wake reason or accept the reset. The PR doesn't add a new opt-out flag
because the goal is to bound session size; introducing an opt-out would
re-open the bloat path this PR is closing.
- No schema or API surface change beyond exporting
`describeSessionResetReason`. No migration. No client-visible API
change.
## Model Used
Claude Opus 4.7 (1M context), model ID `claude-opus-4-7[1m]`. Used in
interactive Claude Code session with extended reasoning, tool use
(Read/Edit/Write/Bash), and verification gates between exploration → fix
→ tests → push.
## 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 the open PR list for similar/duplicate work —
distinct from #4080 (force-fresh follow-up wake — codex/general) and
#4195 (codex session reset on model change); this PR specifically
targets the `heartbeat_timer` reuse path
- [x] I have run tests locally and they pass (12 new + 48 adjacent = 60
tests, no regressions)
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots — N/A, server-only change
- [x] I have updated relevant documentation to reflect my changes — none
needed; the new export carries clear semantics and the run log message
is self-explanatory
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Irene <irene@users.noreply.github.com>
Co-authored-by: Devin Foley <devin@devinfoley.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Co-authored-by: Devin Foley <devin@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The release workflow publishes canary npm packages on every push to
`master`
> - The failing canary job built successfully and published several
packages before npm failed on `@paperclipai/mcp-server`
> - The concrete failure was npm trusted-publishing provenance returning
`TLOG_CREATE_ENTRY_ERROR` because an equivalent Sigstore
transparency-log entry already existed
> - The package version was not visible on npm afterward, so the release
script could not safely treat that error as success by itself
> - This pull request adds a narrow recovery path for that npm
provenance failure and keeps the existing registry verification as the
final source of truth
> - The benefit is that transient duplicate transparency-log failures do
not break canary publication when a package can be republished without
provenance or is already visible on npm
## Linked Issues or Issue Description
Bug fix, no public GitHub issue found in duplicate search.
- What happened: the Release workflow canary publish failed in
`publish_canary` after npm returned `TLOG_CREATE_ENTRY_ERROR` while
publishing `@paperclipai/mcp-server@2026.609.0-canary.2`.
- Expected behavior: canary publishing should either recover from npm's
duplicate transparency-log failure when the package can still be
published, or fail later in registry verification if the package never
appears.
- Steps to reproduce: inspect
https://github.com/paperclipai/paperclip/actions/runs/27230012891/job/80411422155
from push `05cb18cf28074a6d1074c7575c5a44133146e368`.
- Deployment mode: GitHub Actions Release workflow, npm trusted
publishing.
- Duplicate search: no open PRs or issues found for `canary publish TLOG
provenance release` or the failing run/job IDs.
## What Changed
- Added `publish_package_to_npm` in `scripts/release-lib.sh` to wrap
canary/stable package publishing.
- Detects npm's duplicate Sigstore transparency-log error and checks
whether the package version is already visible on npm.
- Retries that exact package once with `--provenance=false` when npm hit
the duplicate tlog error but the version is not visible yet.
- Keeps unrelated publish failures as hard failures.
- Added shell-helper tests with fake `pnpm` and `npm` commands, and
included them in `pnpm test:release-registry`.
## Verification
- `node --test scripts/release-lib.test.mjs`
- `pnpm test:release-registry`
- Confirmed `pnpm publish --dry-run --no-git-checks --tag canary
--access public --provenance=false` is accepted by pnpm 9.15.4.
## Risks
- Low risk: the recovery only triggers when npm output contains both
`TLOG_CREATE_ENTRY_ERROR` and the duplicate transparency-log message.
- Publishing without provenance is a fallback for canary continuity; if
npm still does not expose the package, the existing registry
verification step still fails the release.
- The same helper is used by stable publishing too, but only for this
exact npm provenance failure path.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
This is a release reliability bug fix. I checked `ROADMAP.md`; it does
not duplicate planned core product work.
## Model Used
OpenAI Codex coding agent, GPT-5-class model, tool-enabled local shell
and GitHub CLI workflow, medium reasoning mode.
## 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
- [ ] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Summary
Adds the user-facing stable release changelog for **v2026.609.0**
(released 2026-06-09), generated per
`.agents/skills/release-changelog/SKILL.md` from the diff between
`v2026.529.0` (last stable) and `origin/master` — 119 non-merge commits.
## Highlights covered
- Company Artifacts (page, task-stack grouping, playback, video
thumbnails)
- Collapsible sidebar rail and takeover panes
- Rich issue attachments with video
- Checkbox confirmation interactions
- Information Architecture refresh (experimental) + instance settings
under company settings
- Automated PR quality/security gates + low-trust review containment
## Notes
- No breaking changes — all 5 new migrations (0094–0098) are additive
(backfills, tombstones, annotation links, source-trust tagging, project
icon).
- Contributor list excludes founders and bots per skill rules.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
## Summary
Adds the newly released Claude models from the [models
overview](https://platform.claude.com/docs/en/about-claude/models/overview)
to the `claude_local` adapter's model selector:
- **Claude Fable 5** (`claude-fable-5`) — generally available as of
2026-06-09, Anthropic's most capable widely-released model.
- **Claude Mythos 5** (`claude-mythos-5`) — limited availability
(Project Glasswing).
**Opus 4.8 stays first in the list so it remains the default selection**
— per the request, the new flagship models are *offered* but not
defaulted (not Fable, not Mythos).
## Changes
- `packages/adapters/claude-local/src/index.ts` — add `claude-fable-5`
and `claude-mythos-5` to the adapter model list, right after
`claude-opus-4-8`.
- `packages/adapters/claude-local/src/server/models.ts` — add the Fable
5 Bedrock identifier (`us.anthropic.claude-fable-5-v1`) to the Bedrock
fallback list. Mythos 5 is limited-availability on Bedrock, so it's
intentionally left out of that fallback.
- `server/src/__tests__/adapter-models.test.ts` — assert the new models
are present and that `claude-opus-4-8` remains first (the default).
These flow through the single `claudeModels` source, so they also appear
in the ACPX combined list (`registry.ts` prefixes them with `Claude:`)
and are recognized by the ACPX Claude model filter. The UI selector
reads models dynamically from the adapter, so no UI changes are needed.
## Testing
- `npx vitest run src/__tests__/adapter-models.test.ts` — 13 passed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
## Thinking Path
> - Paperclip is the open source control plane people use to manage AI
agents, work, and company context.
> - The board UI sidebar is the main way operators keep orientation
across companies, projects, agents, issues, and settings.
> - The existing fixed expanded sidebar competes with route-specific
navigation, especially company settings and plugin routes that bring
their own contextual sidebar.
> - A collapsible primary rail preserves global navigation while giving
contextual pages more horizontal room.
> - This pull request adds a persisted collapsed rail, hover/focus peek,
keyboard toggle, and a secondary sidebar takeover model for settings and
plugin `routeSidebar` surfaces.
> - The benefit is a denser board shell that keeps the app rail
available without replacing it when a route needs its own navigation.
## Linked Issues or Issue Description
Paperclip issue: PAP-10638 Create collapsible sidebar branch.
Related GitHub PR found during duplicate search: #3838
(`feat/collapsible-sidebar`) covers a similar sidebar area but is a
different head branch and implementation. This PR intentionally packages
the work from `PAP-10638-collapsable-sidebar` into one reviewable
branch.
Problem description:
The board shell needs a first-class collapsed sidebar mode. Contextual
surfaces such as company settings and plugin route sidebars should not
replace the global app sidebar; they should collapse the app sidebar to
a rail and render their contextual navigation beside it.
## What Changed
- Added desktop collapsed/sidebar-peek state to `SidebarContext`,
including persisted user pins, route collapse requests, and forced
collapse for secondary-sidebar routes.
- Replaced the old resizable sidebar pane with `SidebarShell`, which
supports a fixed 64px rail, persisted expanded width, keyboard/pointer
resizing, and hover/focus peek overlay behavior.
- Updated `Sidebar`, sidebar nav items, project/agent sections, badges,
and account/company menu presentation for expanded, collapsed, and
peeking states.
- Added `RequestCollapsedSidebar` and `SecondarySidebar` so routes and
plugin `routeSidebar` slots can request contextual sidebar layouts
without replacing the primary app sidebar.
- Wired company settings and plugin route sidebars into the
secondary-pane takeover model.
- Added focused Vitest coverage for sidebar state precedence, shell
sizing, nav item rail rendering, keyboard shortcuts, layout takeover
behavior, and route collapse requests.
- Updated plugin authoring docs/spec references for route sidebar
behavior.
## Verification
Targeted local verification passed:
```sh
NODE_ENV=test pnpm run preflight:workspace-links && NODE_ENV=test pnpm exec vitest run ui/src/context/SidebarContext.test.tsx ui/src/components/SidebarShell.test.tsx ui/src/components/Sidebar.test.tsx ui/src/components/Layout.test.tsx ui/src/components/RequestCollapsedSidebar.test.tsx ui/src/components/SidebarNavItem.test.tsx ui/src/components/SidebarAgents.test.tsx ui/src/components/SidebarProjects.test.tsx ui/src/components/KeyboardShortcutsCheatsheet.test.tsx ui/src/hooks/useKeyboardShortcuts.test.tsx
```
Result: 10 test files passed, 88 tests passed.
Additional follow-up verification passed after review fixes:
```sh
NODE_ENV=test pnpm run preflight:workspace-links && NODE_ENV=test pnpm exec vitest run ui/src/components/Layout.test.tsx ui/src/context/SidebarContext.test.tsx && pnpm --filter /ui typecheck
```
Result: 2 test files passed, 28 tests passed, and UI typecheck passed.
Latest PR-head remote checks: Paperclip PR workflow, Snyk, Socket, and
Greptile are green; commitperclip `review` is cancelled in its
security-gate step after filing a non-blocking neutral `security-review`
check.
Notes:
- A direct run without `NODE_ENV=test` loads React's production build in
this workspace, where `act` is unavailable; the command above matches
the repo stable runner's test environment.
- I did not run Playwright/browser e2e or full workspace build/typecheck
in this PR-creation heartbeat.
- QA screenshots are attached in
https://github.com/paperclipai/paperclip/pull/7824#issuecomment-4661968387
for expanded, collapsed rail, hover peek, and settings secondary-sidebar
states.
## Risks
- Medium UI layout risk: this changes the board shell and primary
sidebar composition across many routes.
- Local storage migration risk is low: new collapsed state uses a new
key and existing width storage remains scoped to the sidebar width.
- Plugin route risk: plugin `routeSidebar` slots now render as secondary
panes on desktop, so plugin authors should confirm their route sidebar
content fits a 240px contextual pane.
- Mobile risk appears low because mobile keeps the drawer model and
gates collapsed/peek behavior to desktop.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex coding agent based on GPT-5, with local shell/git/GitHub
CLI tool use. Exact service-side model identifier and context window
were not exposed in this runtime.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have 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
- [ ] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The execution control plane uses issue comments, assignments,
monitors, blockers, and interactions to decide when agent-owned work
should wake and run.
> - Top-level issue comments are actionable issue-thread feedback for
the assignee, but document-scoped comments are review context unless
they are converted into an explicit routing primitive.
> - Document annotation comments were still wired into the same
`issue_commented` wake path as top-level issue comments.
> - That made document activity capable of waking an assignee and
looking like an execution path even when no issue-level handoff
happened.
> - This pull request narrows the wake boundary so document annotation
activity stays document-scoped while normal issue comments continue
waking the assignee.
> - The benefit is fewer spurious wakeups and clearer non-terminal issue
liveness semantics.
## Linked Issues or Issue Description
Internal Paperclip work: [PAP-10613](/PAP/issues/PAP-10613),
[PAP-10640](/PAP/issues/PAP-10640)
Problem description:
- Document annotation thread creation and annotation comments were
treated as assignee wake sources.
- Document-scoped activity should remain visible as document/review
context, but should not by itself act as a queued issue wake, monitor,
approval, interaction response, blocker, or terminal disposition.
- Top-level issue comments should still wake the assignee on
agent-assigned, non-terminal issues.
Related PR search performed:
- Found related prior document annotation work: #6733.
- Found related prior issue-comment wake work and revert context: #7678,
#7765.
- No existing PR for `PAP-10613-why-is-this-task-not-running`.
## What Changed
- Removed the document annotation comment assignee wake helper from
issue routes.
- Kept document annotation reference sync and activity logging intact.
- Documented the distinction between top-level issue comments and
document-scoped comments in `doc/execution-semantics.md`.
- Added route tests proving document/document annotation activity does
not wake the assignee.
- Added route coverage proving top-level board issue comments still wake
the assignee.
## Verification
- `pnpm exec vitest run
server/src/__tests__/document-annotation-routes.test.ts
server/src/__tests__/issue-update-comment-wakeup-routes.test.ts` — 2
files passed, 9 tests passed.
- `pnpm --filter @paperclipai/server typecheck` — passed.
- `git status -sb` — clean branch tracking
`origin/PAP-10613-why-is-this-task-not-running`.
## Risks
- Low to moderate behavior change: document annotation comments no
longer wake the issue assignee automatically.
- Operators who want document feedback to route work must use an
explicit primitive such as assignment, issue-thread comment, agent
mention, issue-thread interaction, approval, blocker, or delegated
follow-up.
- No database migration or public API shape change.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex, GPT-5-based coding agent with shell/tool use enabled.
Exact hosted runtime model identifier beyond GPT-5 was not exposed in
this session.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have 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
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Issue comment wake handoffs are part of the control-plane execution
loop that decides when agents resume work after comments and issue
updates.
> - PR #7678 changed that wake handoff behavior in server issue routes,
heartbeat context, and related tests.
> - The change broke an important workflow after merge, so the safest
immediate fix is to restore the pre-#7678 wake behavior.
> - This pull request reverts the wake-handoff behavior from PR #7678
while keeping narrow review-requested safeguards that prevent known
runtime/test regressions.
> - The benefit is that Paperclip returns to the last known working wake
behavior without reintroducing avoidable UUID skill lookup and
annotation-resolution test gaps.
## Linked Issues or Issue Description
Refs: #7678
Bug context:
- What happened: PR #7678 was reported to have broken an important
Paperclip workflow after it merged.
- Expected behavior: Paperclip should preserve the prior issue comment
wake handoff behavior until a corrected change is ready.
- Steps to reproduce: Use the workflow affected by PR #7678's issue
comment wake handoff changes.
- Paperclip version/commit: `master` after merge commit
`4da79a88c67e54084d40bd18cada5ee5c8be23da`.
- Deployment mode: Paperclip control-plane server behavior.
## What Changed
- Reverted merge commit `4da79a88c67e54084d40bd18cada5ee5c8be23da` from
PR #7678 to restore pre-#7678 wake-handoff behavior.
- Preserved the safe accepted-plan routing check so `parseObject(...)`
is not used as a boolean.
- Preserved UUID filtering for run-scoped skill mentions so legacy
non-UUID skill IDs do not reach a Postgres UUID lookup.
- Restored the annotation thread-resolution test guard that verifies
resolving a thread does not wake the assignee.
## Verification
- `pnpm run preflight:workspace-links && NODE_ENV=test
PAPERCLIP_HOME=/tmp/... PAPERCLIP_INSTANCE_ID=pap10614-revert
TMPDIR=/tmp/... pnpm exec vitest run --project @paperclipai/server
--no-file-parallelism --maxWorkers=1
server/src/__tests__/document-annotation-routes.test.ts
server/src/__tests__/heartbeat-project-env.test.ts
server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts
server/src/__tests__/heartbeat-context-summary.test.ts`
- Result: 4 test files passed, 26 tests passed.
- Earlier targeted revert verification also passed: 4 test files, 50
tests.
## Risks
- This intentionally restores behavior from before PR #7678, so intended
wake-handoff improvements from that PR are removed.
- The PR is no longer a byte-for-byte revert because Greptile identified
two narrow safeguards worth preserving.
- Low migration risk: no schema or dependency changes are included.
- Follow-up work may still be needed to reintroduce the desired wake
handoff behavior without the regression.
## Model Used
OpenAI Codex, GPT-5 coding agent in this Paperclip heartbeat, with
shell/tool execution and repository write access.
## 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
- [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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Operators manage both company-scoped configuration and
instance-level runtime/admin settings from the board UI
> - Instance settings previously lived as their own top-level sidebar
area, separate from the company settings context operators already use
> - That split made settings navigation feel heavier and made instance
configuration less discoverable from the settings tab
> - This pull request moves instance settings under company settings
while preserving the existing instance settings routes and plugin/admin
surfaces
> - The benefit is a smaller primary sidebar and a more coherent
settings hierarchy for operators
## Linked Issues or Issue Description
- Refs #338
- Internal: PAP-10491, PAP-10538
## What Changed
- Moved instance settings navigation under the company settings area.
- Added route helpers and sidebar entries for nested instance settings
paths.
- Updated plugin/admin settings routes to use the company settings
instance scope.
- Preserved legacy instance-settings bookmarks through compatibility
redirects that keep the active company prefix.
- Updated focused UI and plugin tests for the new navigation shape.
- Stabilized the process-loss retry test that was failing the serialized
server shard in CI.
- Rebased the branch onto current `paperclipai/paperclip` `master` and
pushed the current head.
## Verification
- `pnpm exec vitest run
ui/src/components/CompanySettingsSidebar.test.tsx
ui/src/components/access/CompanySettingsNav.test.tsx
ui/src/lib/instance-settings.test.ts
ui/src/components/InstanceSidebar.test.tsx
ui/src/components/Layout.test.tsx
ui/src/components/SidebarAccountMenu.test.tsx
ui/src/pages/PluginPage.test.tsx ui/src/plugins/bridge.test.ts
packages/shared/src/validators/plugin.test.ts`
- `pnpm exec vitest run ui/src/lib/instance-settings.test.ts
ui/src/components/CompanySettingsSidebar.test.tsx
ui/src/components/access/CompanySettingsNav.test.tsx
ui/src/components/Layout.test.tsx ui/src/plugins/bridge.test.ts`
- `pnpm exec vitest run
server/src/__tests__/heartbeat-process-recovery.test.ts -t "queues
exactly one retry when the recorded local pid is dead"`
- `pnpm test:run:serialized -- --shard-index 0 --shard-count 4`
- GitHub PR checks are green on head
`fe7b0955169dcae55cbe10889c1876a70ab0b80c`, including `verify`, `General
tests (server)`, all serialized server shards, build, e2e, policy,
security checks, and Greptile.
- Confirmed the PR diff does not include `pnpm-lock.yaml` or
`.github/workflows` changes.
## Risks
- Medium UI/navigation risk: instance settings links are intentionally
moving under company settings, so stale external bookmarks to legacy
paths rely on the compatibility routing in this branch.
- Low test-only risk from the CI stabilization commit: it makes the
recovery assertion select the actual retry run by `retryOfRunId` instead
of whichever non-original run appears first.
- No database migrations.
- No dependency lockfile or workflow changes.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- OpenAI Codex coding agent based on GPT-5, with shell/tool execution in
a local repository worktree. Exact context window was 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
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip orchestrates AI agents through server-side adapters.
> - Some adapters are bundled as built-ins, while external adapter
plugins can provide newer or organization-specific implementations.
> - The adapter registry already supports external plugins overriding a
built-in type while keeping the built-in available as fallback.
> - The hot-install API still rejected built-in adapter types before
registration, so plugin installation did not match registry behavior.
> - That blocked users from installing an external adapter update for a
built-in adapter type such as `hermes_local`.
> - This pull request removes the hot-install conflict guard and keeps
the existing fallback lifecycle intact.
> - The benefit is consistent adapter override behavior across startup
registration, hot install, pause/resume, and removal.
Fixes#7395
## What Changed
- Allows `POST /api/adapters/install` to register an external adapter
whose type matches a built-in adapter.
- Keeps built-in adapters protected from deletion unless there is an
external plugin record for that adapter type.
- Tightens the install route so `requiresRestart` is only reported on a
true reinstall (existing external plugin record), not on a first-time
override of a built-in adapter type.
- Adds route coverage for installing a built-in type override, pausing
back to the built-in implementation, deleting the override, and
restoring the built-in adapter.
## Verification
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/adapter-routes.test.ts
src/__tests__/adapter-registry.test.ts`
- `pnpm --filter @paperclipai/server typecheck`
- GitHub Actions passed for server tests, typecheck, build, serialized
server suites, e2e, canary dry run, Socket, Snyk, Greptile, and policy
checks on the prior pushed commit before the follow-up review fix.
## Risks
- Low risk: this only changes the hot-install/removal lifecycle for
external plugins targeting a built-in adapter type.
- Built-in adapters remain protected when no external plugin record
exists.
- The existing registry fallback behavior restores the built-in adapter
when an override is paused or removed.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
- OpenAI Codex GPT-5.5 via Hermes Agent for the initial implementation
and verification (terminal/file/GitHub tool use).
- Anthropic Claude Opus 4.7 (claude-opus-4-7) via Paperclip Claude
adapter for the Greptile-feedback follow-up commit (extended-thinking
reasoning, terminal/file/GitHub 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 confirmed
none exist for this hot-install override fix
- [x] I have linked the existing issue with `Fixes #7395`
- [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] 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: HenkDz <henkdz@users.noreply.github.com>
Co-authored-by: Devin Foley <devin@devinfoley.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work, and it runs agents through pluggable adapters.
> - One of those adapters, `gemini_local`
(`packages/adapters/gemini-local/`), runs Google's Gemini CLI on the
same host as the server.
> - For local (in-container) execution, the adapter only probes `PATH`
for the binary (`packages/adapter-utils/src/execution-target.ts`); it
does **not** auto-install — only `sandbox` transport targets install on
demand via `SANDBOX_INSTALL_COMMAND`.
> - The production Docker image bakes in `claude`, `codex`, and
`opencode` so their `*_local` adapters work out of the box, but `gemini`
was never added — so `gemini_local` fails inside the container with a
missing-binary error.
> - This PR adds `@google/gemini-cli@latest` to the image's global
install so `gemini_local` works locally like the other bundled CLIs,
sets `GEMINI_SANDBOX=false` for safe in-container CLI use, and documents
all bundled CLIs.
> - The benefit is plug-and-play Gemini support in Docker with no
per-deployment CLI install step, plus accurate docs (including a
previously-undocumented `opencode` bundle) and a heads-up about Google's
imminent unrestricted-API-key block.
## Linked Issues or Issue Description
No existing issue. Following the **adapter/feature** template fields:
- **Capability:** Run the existing `gemini_local` adapter inside the
official Docker image without a manual CLI install.
- **Problem/motivation:** The image pre-installs `claude`, `codex`, and
`opencode`, but not `gemini`. Because local execution probes `PATH` and
never auto-installs (only sandbox targets do), `gemini_local` runs fail
in-container with a missing-binary error. Operators currently have to
maintain a forked image.
- **Proposed solution:** Add `@google/gemini-cli@latest` to the existing
global `npm install` line; set `GEMINI_SANDBOX=false` in `ENV`.
- **Alternatives considered:** Runtime install at container start
(slower, network-dependent, inconsistent with how the other three CLIs
are handled).
**Related / superseded PRs** (both make the same Dockerfile change and
can be closed if this merges):
- #5912 — `fix(docker): install gemini-cli and normalize persistent
volume permissions`. Same Dockerfile line, but also bundles unrelated
volume-permission and heartbeat-test changes, and a maintainer noted it
now has a merge conflict. I corrected Greptile's `GEMINI_SANDBOX`
reasoning there and it was re-scored 5/5 (see [resolved
thread](https://github.com/paperclipai/paperclip/pull/5912#discussion_r3367332785))
— this PR is the rebased, docs-complete, single-purpose version of that
change.
- #2731 — `Added @google/gemini-cli to the Dockerfile`. One-liner, now
stale and merge-conflicting (predates the `opencode-ai` addition).
> **Note for Greptile:** the `--sandbox=none` reasoning for the Gemini
CLI sandbox concern was already validated on #5912's `Dockerfile:59`
thread and accepted (re-scored 5/5). This PR additionally bakes
`GEMINI_SANDBOX=false` into `ENV` as defense-in-depth, so the concern is
covered both at the adapter layer and the image layer.
## What Changed
- **Dockerfile:** add `@google/gemini-cli@latest` to the production
global npm install (after `opencode-ai`).
- **Dockerfile:** add `GEMINI_SANDBOX=false` to the `ENV` block (matches
the existing `OPENCODE_ALLOW_ALL_MODELS=true` precedent) so a
manually-invoked `gemini` inside the container does not attempt a
Docker-in-Docker sandbox.
- **docs/deploy/docker.md:** rename the section to "Local Adapter CLIs
in Docker"; list all four bundled CLIs mapped to their adapter type keys
(fixes a pre-existing gap — `opencode` was bundled but undocumented);
add `GEMINI_API_KEY` to the example; document per-provider credentials,
the `GEMINI_SANDBOX=false` default, and Google's 2026-06-19
unrestricted-key block with the `gemini auth login` (OAuth) alternative.
## Verification
- `npm view @google/gemini-cli` confirms the package exists, provides
the `gemini` bin, and requires Node `>=20` (the base image is Node 22
LTS). ✅
- Adapter already disables the CLI sandbox per run:
`packages/adapters/gemini-local/src/server/execute.ts` pushes
`--sandbox=none` whenever `config.sandbox` is false (the default). ✅
- Confirmed neither file was modified on `upstream/master`, so this
rebases cleanly with no conflicts. ✅
- Full image build is exercised by CI. (I did not run the multi-stage
`docker build` locally; the change adds one package to an existing,
working `npm install` line.)
- Reviewer manual check: `docker build -t paperclip-local . && docker
run --rm paperclip-local gemini --version` should print the CLI version.
## Risks
- **Low risk.** Adds one npm package to an existing global install and
one inert env var; no application code paths change.
- Minor image-size increase from the additional CLI (consistent with the
three already bundled).
- `@latest` is unpinned — intentionally consistent with the sibling
`@anthropic-ai/claude-code@latest` / `@openai/codex@latest` on the same
line; pinning all of them is a separate decision out of scope here.
## Model Used
Claude Opus 4.8 (model ID `claude-opus-4-8`, 1M-context variant), via
Claude Code with tool use / agentic file editing and web research.
## 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 OR (b) described the
issue in-PR following the relevant issue template
- [ ] I have run tests locally and they pass (no unit tests cover the
Dockerfile; package/bin/engine verified via `npm view`, full build runs
in CI)
- [ ] I have added or updated tests where applicable (N/A — Docker image
+ docs change)
- [ ] If this change affects the UI, I have included before/after
screenshots (N/A)
- [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 (pending CI run on this PR)
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
(pending review)
- [x] I will address all Greptile and reviewer comments before
requesting merge
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
## Thinking Path
> - Paperclip is the open source control plane people use to manage AI
agents for work.
> - Agent runtime state is surfaced in both the server API and the board
UI so operators can tell whether an agent is idle, running, paused, or
in error.
> - When an agent is already in `error`, the existing pause/resume
action slot is not useful because there is no running work to pause.
> - Operators need a direct, audited recovery path that clears the stale
error state only for agents in the same company.
> - This pull request adds a company-scoped clear-error mutation,
exposes the shared API contract, and wires the board action cluster to
show Clear error in the pause/resume slot for errored agents.
> - The benefit is that operators can recover CEO/CTO-style errored
agents without resorting to database edits or unrelated session reset
actions.
## Linked Issues or Issue Description
Refs #4021
Paperclip issue: PAP-10515 — right now the CEO and CTO agents are in
error state, but there is no way to clear the error; they appear
otherwise fine.
## What Changed
- Added shared constants, API path, and agent status type support for a
company-scoped clear-error action.
- Added the server service and route to clear an agent from `error` back
to `idle`, with company access enforcement and activity logging.
- Added OpenAPI/docs coverage for the clear-error endpoint.
- Added backend coverage for service behavior and cross-tenant
authorization.
- Updated the board agent action cluster to show a red-tinted Clear
error button only when `agent.status === "error"`.
- Updated agent properties to show a red active last-error indicator
only while the agent is currently errored.
- Added UI component tests for the error-state action and the non-error
pause/resume behavior.
## Verification
Local:
- `pnpm exec vitest run
server/src/__tests__/agents-service-clear-error.test.ts
server/src/__tests__/agent-cross-tenant-authz-routes.test.ts
ui/src/components/AgentActionButtons.test.tsx`
- `pnpm --filter @paperclipai/ui typecheck`
- `pnpm exec vitest run server/src/__tests__/openapi-routes.test.ts`
PR checks:
- Main Paperclip workflow is green on
`a7378e584d50594e7bd507a1a02985bfaaa5abf8`.
- Greptile is 5/5 with no files requiring special attention and no new
comments on the latest review.
- `commitperclip PR Review` is still red because its security-gate step
canceled after filing a draft advisory; the linked `security-review`
check is neutral and says the draft advisory is not a merge block.
Visual artifact:
- 
## Risks
Low to medium risk. The mutation is intentionally narrow, but reviewers
should check that clearing `lastError`/`lastRunError` and returning to
`idle` is the desired recovery semantics for every adapter state. The
remaining red check is from the external commitperclip security-review
workflow, not from the code/test workflow for this PR.
> 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-family coding model, tool-assisted with local shell,
git, GitHub CLI, and targeted Vitest 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 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
- [ ] 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
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - Operators supervise live agent runs from the issue detail chat
surface.
> - The existing run menu can pause/stop work, but operators sometimes
need to stop the active run and immediately finalize the task outcome.
> - Doing those as separate actions is slower and easier to leave
half-finished.
> - This pull request adds explicit live-run finalization actions to the
issue chat run menu.
> - The benefit is a clearer operator path for stopping a live run and
marking the task done or cancelled in one ordered flow.
## Linked Issues or Issue Description
No public GitHub issue exists for this internal Paperclip task. Internal
task: PAP-10535.
## Subsystem affected
ui/ — React + Vite board UI.
## Problem or motivation
Operators can stop an active run from the issue detail chat, but
finalizing the issue outcome requires a separate status action after the
run is stopped. That extra step makes live-run finalization slower and
easier to leave incomplete.
## Proposed solution
Add explicit issue chat run-menu actions for `Stop and cancel` and `Stop
and done`, where each action cancels the active heartbeat run before
updating the issue status.
## Alternatives considered
Keep the existing two-step flow of cancelling the run first and then
changing issue status separately. That preserves current behavior but
does not solve the operator workflow gap.
## Roadmap alignment
This is a small targeted UI control-plane improvement for supervising
live agent work. It does not duplicate a planned core roadmap item found
in `ROADMAP.md`.
This PR was split from the local `master` branch on June 7, 2026. It
covers the UI-only live-run finalization action. I searched GitHub for
duplicate/related PRs; the results were broader run-control PRs, not
this exact issue-detail menu action.
## What Changed
- Added optional `runFinalizationActions` support to `IssueChatThread`
assistant message run menus.
- Added `Stop and cancel` and `Stop and done` actions on the issue
detail chat tab.
- Each action cancels the active heartbeat run before updating the issue
status.
- Added focused UI coverage to assert cancellation happens before the
status update.
- Addressed Greptile feedback for partial-failure messaging and
duplicate run-state invalidation.
## Verification
- `git diff --check origin/master..HEAD`
- `git diff --check`
- `NODE_ENV=test pnpm exec vitest run ui/src/pages/IssueDetail.test.tsx`
- Storybook screenshot capture for the live-run menu before and after
the finalization actions.
## Screenshots
Before: existing live-run menu only offered the normal stop action.
After: the live-run menu includes `Stop and cancel` and `Stop and done`.
## Risks
- Medium UI behavior risk: the new actions expose faster finalization
controls from the live-run menu. They are gated through the existing
issue detail management surface and still use the existing run cancel
and issue update APIs.
- Low migration risk: no schema, API contract, or dependency changes.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex coding agent based on GPT-5, with shell, git, GitHub CLI,
local test execution, and Playwright browser screenshot capture. Exact
hosted model variant and context-window size 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
- [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
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The heartbeat and issue-comment routes decide when an assigned agent
wakes up and what context it receives.
> - Passive comments and annotation notes can currently wake assignees
even when no actionable state changed.
> - Accepted planning confirmations also need to preserve recent plan
comments so child-issue creation does not lose board/user constraints.
> - Runtime skill mentions should only send UUID ids into database
lookups, because legacy slug-like ids are not valid runtime skill ids.
> - This pull request tightens those wake and handoff rules in one
server-side branch.
> - The benefit is fewer noisy agent wakeups and better accepted-plan
continuation context without changing the task model.
## Linked Issues or Issue Description
Internal Paperclip task: [PAP-10535](/PAP/issues/PAP-10535).
Problem or motivation:
Passive comments and annotation notes could wake the current assignee
even when no actionable state changed, and accepted plan continuations
needed recent plan comments preserved in the wake handoff. Runtime skill
mentions also needed to ignore non-UUID ids before database lookup.
Proposed solution:
Tighten server-side wake routing so passive comments do not wake
assignees unless they reopen the issue, preserve mention-targeted
wakeups, include recent non-deleted plan comments in accepted
confirmation wake payloads, and guard runtime skill mention lookup to
UUID-like ids.
Alternatives considered:
Leaving passive assignee wakeups in place was rejected because it keeps
generating noisy non-actionable heartbeats. Treating every skill
mention-like token as a runtime skill id was rejected because legacy
slug-like ids are not valid runtime skill ids.
Roadmap alignment:
This aligns with the V1 control-plane heartbeat contract by making
wakeups more intentional and preserving handoff context for approved
plans.
This PR was split from the local `master` branch on June 7, 2026. It
covers server-side heartbeat and comment-wakeup behavior only. I
searched GitHub for duplicate/related PRs; the results were broader
heartbeat/run PRs, not this exact passive-comment and accepted-plan
handoff change.
## What Changed
- Filter runtime skill mention extraction so only UUID-like skill ids
are looked up.
- Stop ordinary issue comments and document annotation comments from
waking the current assignee unless the comment reopens the issue.
- Keep mention-targeted wakeups intact while removing passive assignee
wakeups.
- Include recent non-deleted issue comments in accepted-plan
confirmation wake payloads and task markdown.
- Updated focused server tests for the new wakeup and accepted-plan
behavior.
## Verification
- `git diff --check origin/master..HEAD`
- `NODE_ENV=test pnpm exec vitest run
server/src/__tests__/heartbeat-project-env.test.ts
server/src/__tests__/document-annotation-routes.test.ts
server/src/__tests__/issue-comment-reopen-routes.test.ts
server/src/__tests__/issue-update-comment-wakeup-routes.test.ts
server/src/__tests__/heartbeat-context-summary.test.ts
server/src/__tests__/issue-comment-redaction.test.ts`
- `NODE_ENV=test pnpm exec vitest run
server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts
server/src/__tests__/issue-comment-redaction.test.ts
server/src/__tests__/heartbeat-context-summary.test.ts`
- `pnpm --filter /server typecheck`
- PR checks green on head `a379a0264d384510ff8ac4a47fb1e44d7b556f68`
- Greptile rerun green on head
`a379a0264d384510ff8ac4a47fb1e44d7b556f68`: 9 files reviewed, 0 comments
added, 0 unresolved review threads
## Risks
- Medium behavioral risk: agents will no longer wake for passive
comments unless mentioned or unless the comment reopens/resumes the
issue. That is intentional, but any workflow relying on passive assignee
comment wakeups should use explicit mentions or structured resume paths.
- Low migration risk: no schema or migration changes.
> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.
## Model Used
OpenAI Codex coding agent based on GPT-5, with shell, git, GitHub CLI,
and local test execution. Exact hosted model variant and context-window
size 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
- [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
- [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>
