## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work.
> - The server posts a workspace-ready comment after it prepares an
execution workspace or runtime service.
> - The full Markdown card uses too much space in the task thread.
> - The existing system-notice presentation can show the same comment as
a compact row.
> - The server must keep the original body for API clients and expanded
details.
> - This pull request adds structured presentation data at both
workspace-ready call sites.
> - The benefit is a quieter thread with no data loss and no migration.
## Linked Issues or Issue Description
**What existing behavior does this improve?**
The server posts the workspace-ready task comment after workspace
provisioning and adapter-managed runtime startup.
**Current behavior**
The task thread shows a full Markdown comment with strategy, branch,
working directory, services, and warnings. Long branch names can make
this card dominate the thread.
**Proposed behavior**
Show the comment as a compact system-notice row. Expand the row in place
to show the original Markdown body and structured workspace, service,
and warning details. Use a warning tone and open the details by default
when warnings exist.
**Reason and benefit**
The same workspace data is available in the task properties. The compact
row keeps the thread easy to scan while it preserves the full comment
for API consumers and expanded inspection.
**Breaking changes**
None. The comment body stays unchanged. Existing comments without
presentation data keep their current rendering.
## What Changed
- Added workspace-ready presentation and metadata builders.
- Added structured workspace, service, reuse, and warning details.
- Wired both workspace-ready comment paths to send presentation and
metadata options.
- Added focused unit and heartbeat-level tests.
Collapsed notice:
Expanded notice:
## Verification
- `pnpm exec vitest run
server/src/services/workspace-runtime-ready-comment.test.ts
server/src/__tests__/heartbeat-workspace-ready-comment.test.ts` — 8
tests passed.
- `pnpm --filter @paperclipai/server typecheck` — passed.
- `pnpm -r typecheck` — passed.
- `pnpm check:token-gates` — passed.
- `pnpm build` — passed.
- `pnpm test:run` — 300 server files and 405 UI files passed. One
unrelated CLI AWS doctor test detected static credentials from the
runner environment. The same test passed with `AWS_ACCESS_KEY_ID` and
`AWS_SECRET_ACCESS_KEY` removed.
- Built the existing system-notice Storybook story and captured both
compact and expanded states.
- GitHub CI — all latest-head gates passed. One signoff-policy e2e shard
hit a transient checkout-state race and passed on its single rerun.
## Risks
Low risk. This change only adds optional comment presentation data in
two server paths. The body, database schema, API contract, and old
comments remain unchanged. Incorrect metadata would affect only expanded
structured details; focused tests cover the shape and both warning
states.
> 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 with GPT-5 (`gpt-5`, the exact snapshot and context-window
size are not exposed by this runtime). The agent used reasoning,
repository tools, code execution, and visual inspection.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
a388ea1cac
