[codex] feat(watchdog): add task watchdog control plane (#8339)
## 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>
This commit is contained in:
Dotta
+22
-1
@@ -30,7 +30,7 @@ import {
|
||||
countActiveIssueFilters,
|
||||
type IssueFilterState,
|
||||
} from "../lib/issue-filters";
|
||||
import { collectLiveIssueIds } from "../lib/liveIssueIds";
|
||||
import { collectLiveIssueIds, collectSubtreeLiveCounts } from "../lib/liveIssueIds";
|
||||
import { formatAssigneeUserLabel } from "../lib/assignees";
|
||||
import { buildCompanyUserLabelMap, buildCompanyUserProfileMap } from "../lib/company-members";
|
||||
import {
|
||||
@@ -1293,6 +1293,26 @@ export function Inbox() {
|
||||
const flatNavItems = useMemo((): NavEntry[] => {
|
||||
return buildInboxKeyboardNavEntries(groupedSections, collapsedGroupKeys, collapsedInboxParents);
|
||||
}, [collapsedGroupKeys, collapsedInboxParents, groupedSections]);
|
||||
// Roll live descendant runs up to their ancestors across the loaded inbox tree
|
||||
// so a parent that is not itself live can still surface "n live below".
|
||||
const subtreeLiveCounts = useMemo(() => {
|
||||
const nodes: { id: string; parentId: string | null }[] = [];
|
||||
const seen = new Set<string>();
|
||||
const pushIssue = (issue: Issue) => {
|
||||
if (seen.has(issue.id)) return;
|
||||
seen.add(issue.id);
|
||||
nodes.push({ id: issue.id, parentId: issue.parentId });
|
||||
};
|
||||
for (const group of groupedSections) {
|
||||
for (const item of group.displayItems) {
|
||||
if (item.kind === "issue") pushIssue(item.issue);
|
||||
}
|
||||
for (const children of group.childrenByIssueId.values()) {
|
||||
for (const child of children) pushIssue(child);
|
||||
}
|
||||
}
|
||||
return collectSubtreeLiveCounts(nodes, liveIssueIds);
|
||||
}, [groupedSections, liveIssueIds]);
|
||||
const topFlatIndex = useMemo(() => {
|
||||
const map = new Map<string, number>();
|
||||
flatNavItems.forEach((entry, index) => {
|
||||
@@ -2344,6 +2364,7 @@ export function Inbox() {
|
||||
<InboxIssueMetaLeading
|
||||
issue={issue}
|
||||
isLive={liveIssueIds.has(issue.id)}
|
||||
subtreeLiveCount={subtreeLiveCounts.get(issue.id) ?? 0}
|
||||
showStatus={visibleIssueColumnSet.has("status") && availableIssueColumnSet.has("status")}
|
||||
showIdentifier={visibleIssueColumnSet.has("id") && availableIssueColumnSet.has("id")}
|
||||
/>
|
||||
|
||||
@@ -3,6 +3,7 @@
|
||||
import { flushSync } from "react-dom";
|
||||
import { createRoot, type Root } from "react-dom/client";
|
||||
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
||||
import type { InstanceExperimentalSettings as InstanceExperimentalSettingsPayload } from "@paperclipai/shared";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { InstanceExperimentalSettings } from "./InstanceExperimentalSettings";
|
||||
|
||||
@@ -21,6 +22,14 @@ vi.mock("../context/BreadcrumbContext", () => ({
|
||||
useBreadcrumbs: () => ({ setBreadcrumbs: vi.fn() }),
|
||||
}));
|
||||
|
||||
async function act(callback: () => void | Promise<void>) {
|
||||
let result: void | Promise<void> = undefined;
|
||||
flushSync(() => {
|
||||
result = callback();
|
||||
});
|
||||
await result;
|
||||
}
|
||||
|
||||
async function flushReact() {
|
||||
for (let index = 0; index < 5; index += 1) {
|
||||
await Promise.resolve();
|
||||
@@ -31,10 +40,29 @@ async function flushReact() {
|
||||
|
||||
const CONFERENCE_TOGGLE_SELECTOR =
|
||||
'button[aria-label="Toggle conference room chat experimental setting"]';
|
||||
const TASK_WATCHDOGS_TOGGLE_SELECTOR =
|
||||
'button[aria-label="Toggle task watchdogs experimental setting"]';
|
||||
|
||||
function defaultExperimentalSettings(): InstanceExperimentalSettingsPayload {
|
||||
return {
|
||||
enableEnvironments: false,
|
||||
enableIsolatedWorkspaces: false,
|
||||
enableStreamlinedLeftNavigation: false,
|
||||
enableConferenceRoomChat: false,
|
||||
enableIssuePlanDecompositions: false,
|
||||
enableExperimentalFileViewer: false,
|
||||
enableTaskWatchdogs: false,
|
||||
enableCloudSync: false,
|
||||
autoRestartDevServerWhenIdle: false,
|
||||
enableIssueGraphLivenessAutoRecovery: false,
|
||||
issueGraphLivenessAutoRecoveryLookbackHours: 24,
|
||||
};
|
||||
}
|
||||
|
||||
describe("InstanceExperimentalSettings — Conference Room Chat card (PAP-11233)", () => {
|
||||
let container: HTMLDivElement;
|
||||
let root: Root | null = null;
|
||||
let currentExperimentalSettings: InstanceExperimentalSettingsPayload;
|
||||
|
||||
async function renderPage() {
|
||||
root = createRoot(container);
|
||||
@@ -54,11 +82,14 @@ describe("InstanceExperimentalSettings — Conference Room Chat card (PAP-11233)
|
||||
beforeEach(() => {
|
||||
container = document.createElement("div");
|
||||
document.body.appendChild(container);
|
||||
mockInstanceSettingsApi.getExperimental.mockResolvedValue({
|
||||
enableConferenceRoomChat: false,
|
||||
issueGraphLivenessAutoRecoveryLookbackHours: 24,
|
||||
currentExperimentalSettings = defaultExperimentalSettings();
|
||||
mockInstanceSettingsApi.getExperimental.mockImplementation(async () => ({
|
||||
...currentExperimentalSettings,
|
||||
}));
|
||||
mockInstanceSettingsApi.updateExperimental.mockImplementation(async (patch) => {
|
||||
currentExperimentalSettings = { ...currentExperimentalSettings, ...patch };
|
||||
return { ...currentExperimentalSettings };
|
||||
});
|
||||
mockInstanceSettingsApi.updateExperimental.mockResolvedValue({});
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
@@ -80,14 +111,55 @@ describe("InstanceExperimentalSettings — Conference Room Chat card (PAP-11233)
|
||||
});
|
||||
|
||||
it("does not render the toggle even when the stored flag is currently enabled", async () => {
|
||||
mockInstanceSettingsApi.getExperimental.mockResolvedValue({
|
||||
currentExperimentalSettings = {
|
||||
...currentExperimentalSettings,
|
||||
enableConferenceRoomChat: true,
|
||||
issueGraphLivenessAutoRecoveryLookbackHours: 24,
|
||||
});
|
||||
};
|
||||
await renderPage();
|
||||
|
||||
const toggle = container.querySelector(CONFERENCE_TOGGLE_SELECTOR);
|
||||
expect(toggle).toBeNull();
|
||||
expect(mockInstanceSettingsApi.updateExperimental).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("renders and patches the Task Watchdogs experimental toggle on and off", async () => {
|
||||
await renderPage();
|
||||
|
||||
expect(container.textContent).toContain("Task Watchdogs");
|
||||
expect(container.textContent).toContain(
|
||||
"Show task detail controls for configuring watchdog agents that verify stopped task subtrees and restore live paths when work should continue.",
|
||||
);
|
||||
|
||||
const toggle = container.querySelector<HTMLButtonElement>(TASK_WATCHDOGS_TOGGLE_SELECTOR);
|
||||
expect(toggle?.getAttribute("aria-checked")).toBe("false");
|
||||
|
||||
await act(async () => {
|
||||
toggle?.click();
|
||||
});
|
||||
await flushReact();
|
||||
|
||||
expect(mockInstanceSettingsApi.updateExperimental).toHaveBeenCalledWith({
|
||||
enableTaskWatchdogs: true,
|
||||
});
|
||||
expect(toggle?.getAttribute("aria-checked")).toBe("true");
|
||||
|
||||
flushSync(() => {
|
||||
root?.unmount();
|
||||
});
|
||||
root = null;
|
||||
container.textContent = "";
|
||||
await renderPage();
|
||||
|
||||
const enabledToggle = container.querySelector<HTMLButtonElement>(TASK_WATCHDOGS_TOGGLE_SELECTOR);
|
||||
expect(enabledToggle?.getAttribute("aria-checked")).toBe("true");
|
||||
|
||||
await act(async () => {
|
||||
enabledToggle?.click();
|
||||
});
|
||||
await flushReact();
|
||||
|
||||
expect(mockInstanceSettingsApi.updateExperimental).toHaveBeenLastCalledWith({
|
||||
enableTaskWatchdogs: false,
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -2,6 +2,7 @@ import { useEffect, useState } from "react";
|
||||
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
|
||||
import { Clock, FlaskConical, Play, Search } from "lucide-react";
|
||||
import type {
|
||||
InstanceExperimentalSettings,
|
||||
IssueGraphLivenessAutoRecoveryPreview,
|
||||
PatchInstanceExperimentalSettings,
|
||||
} from "@paperclipai/shared";
|
||||
@@ -142,17 +143,39 @@ export function InstanceExperimentalSettings() {
|
||||
queryFn: () => instanceSettingsApi.getExperimental(),
|
||||
});
|
||||
|
||||
const toggleMutation = useMutation({
|
||||
const toggleMutation = useMutation<
|
||||
InstanceExperimentalSettings,
|
||||
Error,
|
||||
PatchInstanceExperimentalSettings,
|
||||
{ previousSettings?: InstanceExperimentalSettings }
|
||||
>({
|
||||
mutationFn: async (patch: PatchInstanceExperimentalSettings) =>
|
||||
instanceSettingsApi.updateExperimental(patch),
|
||||
onSuccess: async () => {
|
||||
onMutate: async (patch) => {
|
||||
await queryClient.cancelQueries({ queryKey: queryKeys.instance.experimentalSettings });
|
||||
const previousSettings = queryClient.getQueryData<InstanceExperimentalSettings>(
|
||||
queryKeys.instance.experimentalSettings,
|
||||
);
|
||||
if (previousSettings) {
|
||||
queryClient.setQueryData<InstanceExperimentalSettings>(
|
||||
queryKeys.instance.experimentalSettings,
|
||||
{ ...previousSettings, ...patch },
|
||||
);
|
||||
}
|
||||
return { previousSettings };
|
||||
},
|
||||
onSuccess: async (updatedSettings) => {
|
||||
setActionError(null);
|
||||
queryClient.setQueryData(queryKeys.instance.experimentalSettings, updatedSettings);
|
||||
await Promise.all([
|
||||
queryClient.invalidateQueries({ queryKey: queryKeys.instance.experimentalSettings }),
|
||||
queryClient.invalidateQueries({ queryKey: queryKeys.health }),
|
||||
]);
|
||||
},
|
||||
onError: (error) => {
|
||||
onError: (error, _patch, context) => {
|
||||
if (context?.previousSettings) {
|
||||
queryClient.setQueryData(queryKeys.instance.experimentalSettings, context.previousSettings);
|
||||
}
|
||||
setActionError(error instanceof Error ? error.message : "Failed to update experimental settings.");
|
||||
},
|
||||
});
|
||||
@@ -216,6 +239,7 @@ export function InstanceExperimentalSettings() {
|
||||
experimentalQuery.data?.enableIssuePlanDecompositions === true;
|
||||
const enableExperimentalFileViewer =
|
||||
experimentalQuery.data?.enableExperimentalFileViewer === true;
|
||||
const enableTaskWatchdogs = experimentalQuery.data?.enableTaskWatchdogs === true;
|
||||
const enableCloudSync = experimentalQuery.data?.enableCloudSync === true;
|
||||
const autoRestartDevServerWhenIdle = experimentalQuery.data?.autoRestartDevServerWhenIdle === true;
|
||||
const enableIssueGraphLivenessAutoRecovery =
|
||||
@@ -400,6 +424,28 @@ export function InstanceExperimentalSettings() {
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="rounded-xl border border-border bg-card p-5">
|
||||
<div className="flex items-start justify-between gap-4">
|
||||
<div className="space-y-1.5">
|
||||
<h2 className="text-sm font-semibold">Task Watchdogs</h2>
|
||||
<p className="max-w-2xl text-sm text-muted-foreground">
|
||||
Show task detail controls for configuring watchdog agents that verify stopped task subtrees and restore
|
||||
live paths when work should continue.
|
||||
</p>
|
||||
</div>
|
||||
<ToggleSwitch
|
||||
checked={enableTaskWatchdogs}
|
||||
onCheckedChange={(checked) =>
|
||||
toggleMutation.mutate({
|
||||
enableTaskWatchdogs: checked,
|
||||
})
|
||||
}
|
||||
disabled={toggleMutation.isPending}
|
||||
aria-label="Toggle task watchdogs experimental setting"
|
||||
/>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section className="rounded-xl border border-border bg-card p-5">
|
||||
<div className="flex items-start justify-between gap-4">
|
||||
<div className="space-y-1.5">
|
||||
|
||||
@@ -140,6 +140,7 @@ import {
|
||||
Copy,
|
||||
Eye,
|
||||
EyeOff,
|
||||
ScanEye,
|
||||
Flag,
|
||||
FileCode2,
|
||||
Hexagon,
|
||||
@@ -3669,6 +3670,16 @@ export function IssueDetail() {
|
||||
</span>
|
||||
) : null}
|
||||
|
||||
{issue.originKind === "task_watchdog" ? (
|
||||
<span
|
||||
className="inline-flex items-center gap-1 rounded-full border border-sky-500/40 bg-sky-500/10 px-2 py-0.5 text-[10px] font-medium text-sky-700 dark:text-sky-300 shrink-0"
|
||||
title="This task is a generated watchdog task. It verifies whether stopped work in the watched task tree is legitimate."
|
||||
>
|
||||
<ScanEye className="h-3 w-3" />
|
||||
Watchdog
|
||||
</span>
|
||||
) : null}
|
||||
|
||||
{issue.workMode === "ask" || issue.workMode === "planning" ? (() => {
|
||||
const workModeMeta = workModeMetaFor(issue.workMode, conferenceRoomChatEnabled);
|
||||
const WorkModeIcon = workModeMeta.icon;
|
||||
|
||||
Reference in New Issue
Block a user