## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - New users start in an onboarding task. The first agent can run the
onboarding interview there or in its chat.
> - #19512 moves the interview card to the chat when the agent asks it
there. The task's card expires.
> - The onboarding task then stays `in_review` with no card, run, wake
or reviewer. Review attention calls it "stalled".
> - Needs you then shows "Choose how this task continues" with Send back
to work / Request changes / Mark task done. A new user cannot know what
to pick. The card stays after the interview, plan approval and handoff
finish in chat.
> - This pull request closes the onboarding task when its interview
moves to chat, and links the chat in a system comment.
> - The benefit is that the user never decides what happens to an
internal task.
## Linked Issues or Issue Description
Refs #19512
**What happened?**
In a browser walk (Codex API path), the user chose "Interview me" in the
onboarding task. Then the user asked in Chat: "Can we do my onboarding
interview here in chat instead of in the task?". The chat card worked.
The onboarding task stayed `in_review`, and Needs you showed "Choose how
this task continues" for it until the end of onboarding.
**What did you expect?**
The onboarding task follows the conversation. It closes with a link to
the chat. No decision about an internal task goes to the user.
**Steps to reproduce**
1. Start onboarding. Choose "Interview me" on the onboarding task.
2. Open Chat with the agent. Ask to do the interview in chat.
3. Open Inbox. See "Choose how this task continues" for the onboarding
task.
## What Changed
- `server/src/services/issue-thread-interactions.ts`: after the chat
question supersedes the onboarding task's interview cards, the
onboarding task is closed (`in_review` → `done`) when no other card is
pending on it. A system comment links to the chat. The change writes an
`issue.updated` activity entry (`source: "onboarding_moved_to_chat"`).
Activity publications and issue post-commit actions run after commit.
- The task stays open if it is not `in_review` or if another card is
still pending (for example a card for a teammate).
- `first-task` skill: tells the agent that the task closes when
onboarding moves to chat. The chat then replaces the task for the rest
of the workflow (plan, proposal cards, child tasks, results). The agent
skips the steps that keep the task `in_review` or make it wait for a
child.
- `onboarding-assets/first-task/README.md`: documents the behavior.
- Tests in `server/src/__tests__/coordinator-handoff.test.ts`: the new
red/green case, plus a case that keeps the task open when another card
is pending.
## Verification
Red on master (fix reverted, same test):
```
FAIL src/__tests__/coordinator-handoff.test.ts > Coordinator canonical handoffs > resolves the onboarding task when its interview moves to the agent chat
AssertionError: expected [ 'stalled' ] to deeply equal []
- []
+ [
+ "stalled",
+ ]
❯ src/__tests__/coordinator-handoff.test.ts:257:40
256| // No "Choose how this task continues" stalled-review card for the…
257| expect(await stalledReviewCards()).toEqual([]);
Tests 1 failed | 3 passed | 24 skipped (28)
```
The test reads the real Needs you feed (`attentionService.list`). On
master it holds a `review` item with `reviewAttentionState: "stalled"`
for the onboarding task. That is the "Choose how this task continues"
card.
Green with the fix:
```
cd server && npx vitest run src/__tests__/coordinator-handoff.test.ts
Tests 28 passed (28)
```
Neighbour suites:
```
npx vitest run src/__tests__/onboarding-first-task-admission.test.ts src/__tests__/issue-onboarding-first-task-routes.test.ts \
src/__tests__/issue-thread-interaction-routes.test.ts src/__tests__/issue-thread-interactions-service.test.ts \
src/__tests__/issue-thread-interactions-telemetry.test.ts src/__tests__/coordinator-handoff.test.ts
Test Files 6 passed (6)
Tests 373 passed (373)
```
- `server` typecheck (`tsc --noEmit`): pass.
- `pnpm verify` exits 2 (the README is a broad input). Required CI
supplies broad coverage.
- Not run: a live browser walk. The Vitest case drives the same service
path the chat uses.
## Risks
- Low risk. The change runs only when an agent asks a question in its
own chat and that question supersedes a pending onboarding-task question
(the #19512 path).
- The onboarding task becomes `done` without a recorded first-task
decision. Later onboarding happens in chat, so nothing waits on this
task. A done onboarding parent still accepts child-completion report
wakes.
- The onboarding task rows are locked before their question rows, the
same order question creation on the task uses (Greptile review
follow-up). The chat row is locked first; no path locks an onboarding
task and then a chat row.
## Model Used
- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, via Claude Code with
tool use (shell, file edits, test runs).
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Server tests that need a real PostgreSQL process must use
./helpers/embedded-postgres.ts instead of constructing embedded-postgres
directly.
The shared helper creates a throwaway data directory and a reserved-safe
loopback port for each test database. This protects the live Paperclip
control-plane Postgres from server vitest runs; see PAP-2033 for the incident
that introduced this guard.
