From 3dec88ce90f46e80a8f5af84d5b0fa320427d8b9 Mon Sep 17 00:00:00 2001 From: Devin Foley Date: Sat, 1 Aug 2026 17:42:42 -0700 Subject: [PATCH] feat(agents): warn when an agent's escalation path routes to a paused manager (#10657) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Agents escalate work up the org chart (`reports_to`), and operators pause agents — notably, instance imports pause every agent by default > - A paused manager does not invalidate the chain (subordinates stay invokable), so nothing surfaces when an operator unpauses workers but leaves their manager paused > - Escalations then dead-letter silently: agent-created issues assigned to the paused manager sit in a queue nothing will ever run > - This pull request computes paused ancestors in the existing org-chain health model and surfaces a non-blocking warning on the agent read models and detail page > - The benefit is that the operator learns their escalation paths are dead before work vanishes into them ## Linked Issues or Issue Description Fixes #10647 (companion to #10648, which refuses agent-initiated assignment to paused agents at write time — this PR makes the standing hazard visible) ## What Changed - `AgentOrgChainHealth` gains two additive, optional fields: `pausedAncestors` (paused agents in the `reports_to` chain) and `escalationWarning` (human-readable, only set when the agent itself can work — a paused/terminated agent's escalation path is moot). Chain validity, invokability, and assignability are byte-identical. - No server route changes needed: the fields flow through every existing agent read model (list, detail, org chart) since they ride the same `getAgentWorkEligibility` computation. - Agent detail page shows an amber "Escalation path is paused" banner (same visual language as the invalid-chain banner, but non-blocking) with the warning text naming the paused manager and the two remedies. ## Verification - `pnpm vitest run packages/shared/src/agent-eligibility.test.ts` — 5 new cases: paused direct manager warns; paused grandparent through a healthy manager warns; the agent itself paused → no warning (but ancestors still reported); fully active chain → no warning, empty list; terminated ancestor keeps the invalid-chain classification without double-counting as paused. - Full `@paperclipai/shared` suite (392 tests) and `agent-eligibility-routes` (54) unchanged. - `tsc --noEmit` in shared, server, and ui. ## Risks - Low. Purely additive fields plus one UI banner; no behavior gates on the new data. ## Model Used Claude Fable 5 (`claude-fable-5`, Anthropic) via Claude Code — extended thinking, agentic tool use. No other models involved. ## 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 - [ ] 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 --- packages/shared/src/agent-eligibility.test.ts | 66 +++++++++++++++++++ packages/shared/src/agent-eligibility.ts | 25 +++++++ ui/src/pages/AgentDetail.tsx | 10 +++ 3 files changed, 101 insertions(+) diff --git a/packages/shared/src/agent-eligibility.test.ts b/packages/shared/src/agent-eligibility.test.ts index fba9d41d89..ee85624d2e 100644 --- a/packages/shared/src/agent-eligibility.test.ts +++ b/packages/shared/src/agent-eligibility.test.ts @@ -156,3 +156,69 @@ describe("agent work eligibility", () => { expect(eligibility.invokabilityReason).toBe("invalid_org_chain"); }); }); + +describe("paused escalation path warning", () => { + it("warns when an active agent's manager is paused", () => { + const manager = agent({ id: "manager-1", name: "CTO", status: "paused", reportsTo: null }); + const coder = agent({ id: "agent-1", name: "Coder", status: "active", reportsTo: "manager-1" }); + const result = getAgentWorkEligibility({ agent: coder, agents: [coder, manager] }); + + expect(result.invokable).toBe(true); + expect(result.orgChainHealth.status).toBe("healthy"); + expect(result.orgChainHealth.pausedAncestors).toEqual([ + { id: "manager-1", name: "CTO", status: "paused" }, + ]); + expect(result.orgChainHealth.escalationWarning).toContain("route to paused agent CTO"); + expect(result.orgChainHealth.escalationWarning).toContain("never runs"); + }); + + it("warns about a paused grandparent through a healthy manager", () => { + const executive = agent({ id: "exec-1", name: "CEO", status: "paused", reportsTo: null }); + const manager = agent({ id: "manager-1", name: "CTO", status: "active", reportsTo: "exec-1" }); + const coder = agent({ id: "agent-1", name: "Coder", status: "active", reportsTo: "manager-1" }); + const result = getAgentWorkEligibility({ agent: coder, agents: [coder, manager, executive] }); + + expect(result.orgChainHealth.pausedAncestors).toEqual([ + { id: "exec-1", name: "CEO", status: "paused" }, + ]); + expect(result.orgChainHealth.escalationWarning).toContain("CEO"); + }); + + it("does not warn when the agent itself is paused", () => { + const manager = agent({ id: "manager-1", name: "CTO", status: "paused", reportsTo: null }); + const coder = agent({ id: "agent-1", name: "Coder", status: "paused", reportsTo: "manager-1" }); + const result = getAgentWorkEligibility({ agent: coder, agents: [coder, manager] }); + + expect(result.orgChainHealth.escalationWarning).toBeNull(); + expect(result.orgChainHealth.pausedAncestors).toEqual([ + { id: "manager-1", name: "CTO", status: "paused" }, + ]); + }); + + it("does not warn for agents with unknown statuses", () => { + const manager = agent({ id: "manager-1", name: "CTO", status: "paused", reportsTo: null }); + const coder = agent({ id: "agent-1", name: "Coder", status: "mystery", reportsTo: "manager-1" }); + const result = getAgentWorkEligibility({ agent: coder, agents: [coder, manager] }); + + expect(result.invokable).toBe(false); + expect(result.orgChainHealth.escalationWarning).toBeNull(); + }); + + it("does not warn on a fully active chain", () => { + const manager = agent({ id: "manager-1", name: "CTO", status: "active", reportsTo: null }); + const coder = agent({ id: "agent-1", name: "Coder", status: "active", reportsTo: "manager-1" }); + const result = getAgentWorkEligibility({ agent: coder, agents: [coder, manager] }); + + expect(result.orgChainHealth.escalationWarning).toBeNull(); + expect(result.orgChainHealth.pausedAncestors).toEqual([]); + }); + + it("keeps invalid-chain classification for terminated ancestors, without duplicating them as paused", () => { + const manager = agent({ id: "manager-1", name: "CTO", status: "terminated", reportsTo: null }); + const coder = agent({ id: "agent-1", name: "Coder", status: "active", reportsTo: "manager-1" }); + const result = getAgentWorkEligibility({ agent: coder, agents: [coder, manager] }); + + expect(result.orgChainHealth.status).toBe("invalid_org_chain"); + expect(result.orgChainHealth.pausedAncestors).toEqual([]); + }); +}); diff --git a/packages/shared/src/agent-eligibility.ts b/packages/shared/src/agent-eligibility.ts index ae53bb57bf..bf658da7e9 100644 --- a/packages/shared/src/agent-eligibility.ts +++ b/packages/shared/src/agent-eligibility.ts @@ -45,6 +45,15 @@ export interface AgentOrgChainHealth { firstInvalidAncestor: AgentInvalidOrgChainAncestor | null; invalidAncestors: AgentInvalidOrgChainAncestor[]; repairGuidance: string | null; + /** + * Paused ancestors of a non-paused agent. A paused manager does not make + * the chain invalid (the agent stays invokable), but escalations routed to + * it dead-letter: assigned work never runs and nothing surfaces it. This is + * a warning, not a block. + */ + pausedAncestors?: AgentInvalidOrgChainAncestor[]; + /** Human-readable warning when the escalation path routes to a paused agent. */ + escalationWarning?: string | null; } export interface AgentWorkEligibility { @@ -121,6 +130,7 @@ export function getAgentOrgChainHealth(input: { const byId = new Map(input.agents.map((agent) => [agent.id, agent])); const fullChain: AgentOrgChainEntry[] = [chainEntry(input.agent, 0, "self")]; const invalidAncestors: AgentInvalidOrgChainAncestor[] = []; + const pausedAncestors: AgentInvalidOrgChainAncestor[] = []; const seen = new Set([input.agent.id]); let current = input.agent; @@ -171,12 +181,25 @@ export function getAgentOrgChainHealth(input: { if (parent.status === "terminated") { invalidAncestors.push(invalidAncestor(parent)); } + if (parent.status === "paused") { + pausedAncestors.push({ id: parent.id, name: parent.name, status: "paused" }); + } current = parent; depth += 1; } const firstInvalidAncestor = invalidAncestors[0] ?? null; + // Only warn for agents that can themselves receive and run work: a paused, + // terminated, or unknown-status agent's escalation path is moot until it is + // invokable again. Allowlist on purpose — a denylist complement would treat + // unrecognized statuses as workable and warn misleadingly. + const agentCanWork = isAgentStatusInvokable(input.agent.status); + const firstPausedAncestor = pausedAncestors[0] ?? null; + const escalationWarning = agentCanWork && firstPausedAncestor + ? `Escalations from ${input.agent.name} route to paused agent ${firstPausedAncestor.name}. ` + + `Work assigned to a paused agent never runs; unpause ${firstPausedAncestor.name} or change who this agent reports to.` + : null; return { status: firstInvalidAncestor ? "invalid_org_chain" : "healthy", reason: firstInvalidAncestor @@ -192,6 +215,8 @@ export function getAgentOrgChainHealth(input: { repairGuidance: firstInvalidAncestor ? buildRepairGuidance(input.agent, firstInvalidAncestor) : null, + pausedAncestors, + escalationWarning, }; } diff --git a/ui/src/pages/AgentDetail.tsx b/ui/src/pages/AgentDetail.tsx index 53cc43fdc9..b4bd9138bd 100644 --- a/ui/src/pages/AgentDetail.tsx +++ b/ui/src/pages/AgentDetail.tsx @@ -1051,6 +1051,7 @@ export function AgentDetail() { } const isPendingApproval = agent.status === "pending_approval"; const hasInvalidOrgChain = agent.orgChainHealth?.status === "invalid_org_chain"; + const pausedEscalationWarning = !hasInvalidOrgChain ? agent.orgChainHealth?.escalationWarning ?? null : null; const showConfigActionBar = (activeView === "configuration" || activeView === "instructions") && (configDirty || configSaving); const showLeftAgentNotice = agentMembershipState === "left" && !dismissedLeftAgentIds.has(agent.id); const agentMembershipPending = @@ -1097,6 +1098,15 @@ export function AgentDetail() { ) : null} + {pausedEscalationWarning ? ( +
+ +
+

Escalation path is paused

+

{pausedEscalationWarning}

+
+
+ ) : null} {hasInvalidOrgChain ? (