a71c4b6782
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The task lifecycle and recovery subsystems decide when agent work is still productive, stalled, or ready for review. > - Existing recovery paths can observe stopped or incomplete work, but there was no first-class per-task watchdog model with scoped review permissions. > - Watchdog follow-ups also need strict boundaries so recovery/status-only runs cannot mutate approvals or perform deliverable work. > - This pull request adds the task watchdog data model, API/service layer, scheduler/review flow, adapter wake context, UI configuration surfaces, and docs. > - The branch has been rebased onto current `paperclipai/paperclip` `master`; the watchdog migration is now ordered after master's latest migrations as `0104_issue_watchdogs`. > - The benefit is a more explicit task-review loop that preserves Paperclip's single-assignee and governance invariants while making stalled work easier to route. ## Linked Issues or Issue Description No linked GitHub issue. Paperclip task: [PAP-11275](/PAP/issues/PAP-11275). ## Problem or motivation Task recovery needs a first-class watchdog path that can inspect stopped work and create scoped follow-ups without bypassing normal task ownership. Board/UI users need a way to configure watchdogs on tasks and see watchdog-related live work. Recovery/status-only runs must remain limited to status reporting and must not create approvals, link approvals, or submit approval comments. ## Proposed solution Add a task-watchdog data model, scheduler/classifier, scoped mutation guard, adapter wake context, API/UI configuration surfaces, and documentation so watchdog agents can review stopped task subtrees under explicit boundaries. ## Alternatives considered Reuse the existing recovery-action flow only. That would keep stopped-work detection implicit, make per-task watchdog assignment harder to expose in the UI, and would not provide a durable scoped-review issue for stalled task trees. ## Roadmap alignment This is Paperclip control-plane lifecycle infrastructure for task execution and recovery. I checked `ROADMAP.md`; this PR does not duplicate an existing planned core item. ## What Changed - Added issue watchdog schema, migration, shared contracts, validators, CRUD API, and service support. - Added task watchdog scheduler/classifier behavior, scoped mutation enforcement, adapter wake context, and default watchdog mandate guidance. - Added UI surfaces for configuring watchdogs on new/existing tasks, viewing watchdog activity, and exposing the experimental setting. - Added docs for the user-facing task watchdog workflow and implementation semantics. - Gated new-task watchdog setup behind `enableTaskWatchdogs` and blocked cheap status-only recovery runs from approval mutations. - Rebased onto current `master` and renumbered the idempotent watchdog migration from the branch-local `0102_issue_watchdogs` slot to `0104_issue_watchdogs`. - Addressed Greptile feedback by loading watchdog classifier input with a recursive subtree query and centralizing the watchdog origin-kind constant. - Added and updated focused server/UI tests for watchdog routes, scheduler/classifier behavior, scope boundaries, live task visibility, settings, and new issue dialog behavior. ## Verification - `pnpm vitest run server/src/__tests__/task-watchdogs-scheduler.test.ts server/src/__tests__/task-watchdogs-classifier.test.ts` - `pnpm vitest run server/src/__tests__/approval-routes-idempotency.test.ts server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts` - `pnpm vitest run ui/src/components/NewIssueDialog.test.tsx` - `pnpm --filter @paperclipai/server typecheck` - `git diff --check` - Verified the PR diff does not include `pnpm-lock.yaml` or `.github/workflows`. ## Risks - Medium risk: this introduces a new task lifecycle surface touching DB schema, server routes/services, adapter wake context, and UI task configuration. - Watchdog scheduling behavior depends on the new experimental setting and runtime context checks behaving consistently across local and production agents. - The watchdog migration is idempotent (`IF NOT EXISTS` / duplicate-object guards) so users who tried the previous branch-local migration number should not get duplicate-object failures. - CI and the second Greptile pass are pending after the latest review-fix push. > 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-class coding agent in the Paperclip workspace. Exact runtime model id and context window were not exposed to the agent; tool use and local command execution were 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) - [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 per Paperclip task instruction: do not add screenshots/images to this PR unless they are specifically part of the work. - [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: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
124 lines
3.9 KiB
TypeScript
124 lines
3.9 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import type { LiveRunForIssue } from "../api/heartbeats";
|
|
import { collectLiveIssueIds, collectSubtreeLiveCounts } from "./liveIssueIds";
|
|
|
|
describe("collectLiveIssueIds", () => {
|
|
it("keeps only runs linked to issues", () => {
|
|
const liveRuns: LiveRunForIssue[] = [
|
|
{
|
|
id: "run-1",
|
|
status: "running",
|
|
invocationSource: "scheduler",
|
|
triggerDetail: null,
|
|
startedAt: "2026-04-20T10:00:00.000Z",
|
|
finishedAt: null,
|
|
createdAt: "2026-04-20T10:00:00.000Z",
|
|
agentId: "agent-1",
|
|
agentName: "Coder",
|
|
adapterType: "codex_local",
|
|
issueId: "issue-1",
|
|
},
|
|
{
|
|
id: "run-2",
|
|
status: "queued",
|
|
invocationSource: "scheduler",
|
|
triggerDetail: null,
|
|
startedAt: null,
|
|
finishedAt: null,
|
|
createdAt: "2026-04-20T10:01:00.000Z",
|
|
agentId: "agent-2",
|
|
agentName: "Reviewer",
|
|
adapterType: "codex_local",
|
|
issueId: null,
|
|
},
|
|
{
|
|
id: "run-3",
|
|
status: "running",
|
|
invocationSource: "scheduler",
|
|
triggerDetail: null,
|
|
startedAt: "2026-04-20T10:02:00.000Z",
|
|
finishedAt: null,
|
|
createdAt: "2026-04-20T10:02:00.000Z",
|
|
agentId: "agent-3",
|
|
agentName: "Builder",
|
|
adapterType: "codex_local",
|
|
issueId: "issue-1",
|
|
},
|
|
{
|
|
id: "run-4",
|
|
status: "running",
|
|
invocationSource: "scheduler",
|
|
triggerDetail: null,
|
|
startedAt: "2026-04-20T10:03:00.000Z",
|
|
finishedAt: null,
|
|
createdAt: "2026-04-20T10:03:00.000Z",
|
|
agentId: "agent-4",
|
|
agentName: "Fixer",
|
|
adapterType: "codex_local",
|
|
issueId: "issue-2",
|
|
},
|
|
{
|
|
id: "run-5",
|
|
status: "succeeded",
|
|
invocationSource: "scheduler",
|
|
triggerDetail: null,
|
|
startedAt: "2026-04-20T10:04:00.000Z",
|
|
finishedAt: "2026-04-20T10:05:00.000Z",
|
|
createdAt: "2026-04-20T10:04:00.000Z",
|
|
agentId: "agent-5",
|
|
agentName: "Done",
|
|
adapterType: "codex_local",
|
|
issueId: "completed-issue",
|
|
},
|
|
];
|
|
|
|
expect([...collectLiveIssueIds(liveRuns)]).toEqual(["issue-1", "issue-2"]);
|
|
});
|
|
});
|
|
|
|
describe("collectSubtreeLiveCounts", () => {
|
|
const tree = [
|
|
{ id: "root", parentId: null },
|
|
{ id: "child-a", parentId: "root" },
|
|
{ id: "child-b", parentId: "root" },
|
|
{ id: "grandchild", parentId: "child-a" },
|
|
];
|
|
|
|
it("rolls a live descendant up to every ancestor without crediting itself", () => {
|
|
const counts = collectSubtreeLiveCounts(tree, new Set(["grandchild"]));
|
|
expect(counts.get("root")).toBe(1);
|
|
expect(counts.get("child-a")).toBe(1);
|
|
expect(counts.has("child-b")).toBe(false);
|
|
// The live issue itself never appears in its own subtree count.
|
|
expect(counts.has("grandchild")).toBe(false);
|
|
});
|
|
|
|
it("counts multiple live descendants under a shared ancestor", () => {
|
|
const counts = collectSubtreeLiveCounts(tree, new Set(["child-b", "grandchild"]));
|
|
expect(counts.get("root")).toBe(2);
|
|
expect(counts.get("child-a")).toBe(1);
|
|
expect(counts.has("child-b")).toBe(false);
|
|
});
|
|
|
|
it("ignores live issues that are not part of the loaded tree", () => {
|
|
const counts = collectSubtreeLiveCounts(tree, new Set(["not-loaded"]));
|
|
expect(counts.size).toBe(0);
|
|
});
|
|
|
|
it("returns an empty map when nothing is live", () => {
|
|
expect(collectSubtreeLiveCounts(tree, new Set()).size).toBe(0);
|
|
expect(collectSubtreeLiveCounts(undefined, new Set(["x"])).size).toBe(0);
|
|
});
|
|
|
|
it("does not infinite-loop on a cyclic parent chain", () => {
|
|
const cyclic = [
|
|
{ id: "a", parentId: "b" },
|
|
{ id: "b", parentId: "a" },
|
|
];
|
|
const counts = collectSubtreeLiveCounts(cyclic, new Set(["a"]));
|
|
// a -> b counted once; the cycle back to a is guarded by the seen set.
|
|
expect(counts.get("b")).toBe(1);
|
|
expect(counts.has("a")).toBe(false);
|
|
});
|
|
});
|