Task Watchdogs

Sometimes an agent stops work for the wrong reason. It misreads a blocker, declares an issue "done" without real proof, accepts a stale plan confirmation, or hits a recoverable error and gives up. When that happens, nothing wakes anyone — the issue tree just goes quiet and sits there.

A task watchdog is an agent you put in charge of double-checking a stopped issue tree and putting it back into motion when stopping was a mistake. You attach it to one issue; it watches that issue and its descendants. When everything in that subtree has come to rest and there's no live path forward, Paperclip wakes the watchdog to read the evidence and decide whether the stop is genuine — or whether work should continue.

Think of it as a second pass on stopped work, without re-running the original assignee. It's verification-shaped, not execution-shaped: it checks what other agents claimed against what's actually in the thread, then either accepts the stop or restores a live path.

Heads up: Watchdogs are opt-in, per issue. There's no global "watch everything" switch — you decide which trees are worth the extra pass.

Three things called "watchdog"

The word shows up in a few places in Paperclip. Keep them straight:

• Task watchdog (this page) — an agent you assign to a specific issue. Fires only when the whole watched subtree has stopped. Configurable.
• Silent active-run watchdog — automatic monitoring of a single running agent for output silence. No configuration, nothing to set up. (See your adapter's inactivity settings, e.g. codex-local's outputInactivityTimeoutMs.)
• Liveness recovery — automatic restart of stalled agent-owned issues.

Only the first one is something you turn on by hand.

When a watchdog wakes

A watchdog stays asleep while there's still live work to do. It wakes only when every leaf in the watched subtree has come to rest — done, cancelled, blocked, in review, or waiting on an interaction — and there's no continuation path left to follow.

At that point Paperclip hands the watchdog agent the tree and a mandate: treat every stopped leaf as a claim that has to be verified, not a fact to be trusted. The watchdog then:

• Leaves genuinely-finished leaves alone, with a short note on what it checked.
• Restores a live path when a leaf isn't really done — by reopening the issue, reassigning it, commenting actionable next steps, opening a follow-up child issue inside the watched subtree, or accepting an eligible plan confirmation.
• Confirms real blockers, leaving a clear waiting state that names who can unblock it and what happens next.

It will not take "I couldn't" or "waiting for approval" at face value — that's the whole point.

Set a watchdog

A watchdog has three parts:

An issue can have at most one active watchdog. Re-assigning the agent or editing the instructions resets the watchdog's memory of what it already reviewed, so the next scan starts fresh.

From the app

Two places let you set one:

• New issue dialog — open the three-dot menu and pick the Watchdog row. Choose an agent and, optionally, type instructions. The watchdog is created together with the issue, and a chip in the dialog footer shows your choice.
• Issue properties — find the Watchdog row next to Monitor. It reads Set watchdog when empty; once configured it shows the agent and a preview of your instructions. Click it to open the editor, where you pick an agent, write instructions, and hit Set watchdog (or Update). There's a Remove button too. When a watchdog run has spun up a review task, the row shows a small badge linking straight to it.

From the API

GET    /api/issues/:issueId/watchdog
PUT    /api/issues/:issueId/watchdog   { "agentId": "...", "instructions": "..." }
DELETE /api/issues/:issueId/watchdog

PUT is an upsert — it creates the watchdog or updates the existing one. DELETE disables it (the row is kept for audit history, not hard-deleted). All three need write access to the watched issue, and each one writes an activity record (issue.watchdog_created, issue.watchdog_updated, issue.watchdog_removed) with the actor and run id.

Writing good instructions

Instructions work best when they tell the watchdog what evidence to look at and what shortcuts to refuse. For example:

Before accepting any leaf as done, check there's a green CI run linked in the comments. If there isn't, reopen the leaf and ask for one.

Don't accept a plan that proposes more than five subtasks without my review. Leave the issue in review and ping me.

If a leaf is blocked on the marketing team, accept the wait — but make sure the blocker names who can unblock it.

What instructions can't do: reach outside the watched subtree, approve board-level decisions, expand the kinds of interactions the watchdog can resolve, or relax its safety limits. The server enforces those boundaries no matter what the instructions say.

What a watchdog can't do

A watchdog operates under hard, server-enforced limits — custom instructions can tighten them but never loosen them:

• It stays inside the watched subtree. No changes to issues outside that tree, and nothing cross-company.
• It can't approve board-only decisions — spend, hiring, security-sensitive interactions — or bypass an execution-policy stage that requires a named reviewer or approver.
• It can't touch its own configuration or create another watchdog for the same tree, and it can't wake itself.

Any move that crosses those lines is rejected at the API layer, so the watchdog has to take a legitimate path instead: comment, open an in-subtree follow-up, leave a valid waiting state, or escalate to a human.

When not to use one

A task watchdog earns its keep when a tree has many leaves and you want a second pass before trusting "all green," when the original assignee tends to call things done too early, or when the work matters enough that a missed false-stop is worth an extra agent run.

It's the wrong tool when you want to:

• Watch a single running process for silence — that's the automatic silent active-run watchdog, no setup needed.
• Recover a stalled agent-owned issue — that's automatic too.
• Gate board-level or security-sensitive decisions — a watchdog can't resolve those.
• Stand in for a human reviewer on a typed execution-policy stage — it can't bypass typed participants.

And if what you really want is "wake me when this is done," reach for a routine or an issue-thread interaction instead.

Where to go next

• Heartbeats & Routines — timer- and event-driven wakes, the other way to keep work moving.
• Projects — how issue trees are organized in the first place.