## Thinking Path
> - Paperclip orchestrates AI agents for zero-human companies
> - Reliable execution depends on heartbeat routing, issue lifecycle
semantics, telemetry, and a fast enough local verification loop to keep
regressions visible
> - The remaining commits on this branch were mostly server/runtime
correctness fixes plus test and documentation follow-ups in that area
> - Those changes are logically separate from the UI-focused
issue-detail and workspace/navigation branches even when they touch
overlapping issue APIs
> - This pull request groups the execution reliability, heartbeat,
telemetry, and tooling changes into one standalone branch
> - The benefit is a focused review of the control-plane correctness
work, including the follow-up fix that restored the implicit
comment-reopen helpers after branch splitting
## What Changed
- Hardened issue/heartbeat execution behavior, including self-review
stage skipping, deferred mention wakes during active execution, stranded
execution recovery, active-run scoping, assignee resolution, and
blocked-to-todo wake resumption
- Reduced noisy polling/logging overhead by trimming issue run payloads,
compacting persisted run logs, silencing high-volume request logs, and
capping heartbeat-run queries in dashboard/inbox surfaces
- Expanded telemetry and status semantics with adapter/model fields on
task completion plus clearer status guidance in docs/onboarding material
- Updated test infrastructure and verification defaults with faster
route-test module isolation, cheaper default `pnpm test`, e2e isolation
from local state, and repo verification follow-ups
- Included docs/release housekeeping from the branch and added a small
follow-up commit restoring the implicit comment-reopen helpers that were
dropped during branch reconstruction
## Verification
- `pnpm vitest run
server/src/__tests__/issue-comment-reopen-routes.test.ts
server/src/__tests__/issue-telemetry-routes.test.ts`
- `pnpm vitest run server/src/__tests__/http-log-policy.test.ts
server/src/__tests__/heartbeat-run-log.test.ts
server/src/__tests__/health.test.ts`
- `server/src/__tests__/activity-service.test.ts`,
`server/src/__tests__/heartbeat-comment-wake-batching.test.ts`, and
`server/src/__tests__/heartbeat-process-recovery.test.ts` were attempted
on this host but the embedded Postgres harness reported
init-script/data-dir problems and skipped or failed to start, so they
are noted as environment-limited
## Risks
- Medium: this branch changes core issue/heartbeat routing and
reopen/wakeup behavior, so regressions would affect agent execution flow
rather than isolated UI polish
- Because it also updates verification infrastructure, reviewers should
pay attention to whether the new tests are asserting the right failure
modes and not just reshaping harness behavior
## Model Used
- OpenAI Codex coding agent (GPT-5-class runtime in Codex CLI; exact
deployed model ID is not exposed in this environment), reasoning
enabled, tool use and local code execution enabled
## 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)
- [ ] 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] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
When an agent is woken by a comment (Resume Delta or Wake Payload), the
skill now explicitly instructs it to skip Steps 1-4 (identity, approvals,
inbox, pick work) and go directly to checkout. This prevents agents from
wastefully fetching their full assignment list and announcing "checking my
paperclip tasks" when they already know exactly which issue to work on.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Add explicit Paperclip skill guidance for reviewer/approver heartbeats and document that execution-policy decisions use PATCH /api/issues/:issueId rather than a separate endpoint.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Document blockedByIssueIds field, issue_blockers_resolved and
issue_children_completed wake reasons, and blockedBy/blocks response
arrays in both SKILL.md and api-reference.md so agents know how to
set and use first-class issue dependencies.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Greptile flagged that worked examples in task-workflow.md and
api-reference.md still used ["todo"] instead of the full
expectedStatuses array. Aligned them with the rest of the PR.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Root cause: when someone commented on an in_review task, the heartbeat
wakeup was triggered but the agent couldn't re-checkout the task because
expectedStatuses only included todo/backlog/blocked. The in_review status
was never handled in the checkout flow or the heartbeat procedure.
Changes:
- Add wakeCommentId to issue_commented and issue_reopened_via_comment
context snapshots (consistent with issue_comment_mentioned)
- Add in_review to checkout expectedStatuses in heartbeat skill
- Update Step 3 fallback query to include in_review status
- Update Step 4 to prioritize in_review tasks when woken by comment
- Add explicit issue_commented wake reason handling in Step 4
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Adds a new skill that documents how to create and manage Paperclip
routines — recurring tasks that fire on a schedule, webhook, or API
call and dispatch an execution issue to the assigned agent.
Drop "api" from the trigger kind dropdown and disable the "webhook"
option with a "COMING SOON" label until it's ready.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
- Add updateCompanyBrandingSchema restricting agent-updatable fields to name,
description, brandColor, and logoAssetId
- Update PATCH /api/companies/:companyId to allow CEO agents with branding-only
fields while keeping admin fields (status, budget, etc.) board-only
- Allow agents to GET /api/companies/:companyId for reading company info
- issuePrefix (company slug) remains protected — not in any update schema
- Document branding APIs in SKILL.md quick reference and api-reference.md
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Add upload, list, get content, and delete attachment endpoints
to the Key Endpoints table so agents know about the attachments API.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Resolve conflicts by keeping the issue-documents work alongside upstream heartbeat-context, worktree branding, and adapter runtime updates.
Co-Authored-By: Paperclip <noreply@paperclip.ing>
Add commit co-author requirement for Paperclip agents and fix markdown
lint issues (blank lines before lists, table column alignment).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document the agent local-cli command for manual CLI usage and add a
step-by-step self-test playbook for validating assignment flows.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
New Steps 3-5 in the release skill:
- Step 3: Publish canary to npm with --tag canary (latest untouched)
- Step 4: Smoke test canary in Docker (uses existing smoke infrastructure)
- Step 5: Promote canary to latest after verification
Also updates idempotency table for new intermediate states (canary
published but not promoted) and adds release flow summary.
Script changes still needed: --canary flag for release.sh, --promote
command for dist-tag promotion.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
