feat(agents): warn when an agent's escalation path routes to a paused manager (#10657)

## 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

@@ -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([]);
+  });
+});

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<string>([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,
   };
 }
 

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() {
           </button>
         </div>
       ) : null}
+      {pausedEscalationWarning ? (
+        <div className="flex items-start gap-3 border border-amber-300/35 bg-amber-300/10 px-3 py-2 text-sm text-amber-900 dark:text-amber-100">
+          <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
+          <div className="min-w-0 space-y-1">
+            <p className="font-medium">Escalation path is paused</p>
+            <p className="text-amber-900/90 dark:text-amber-100/90">{pausedEscalationWarning}</p>
+          </div>
+        </div>
+      ) : null}
       {hasInvalidOrgChain ? (
         <div className="flex items-start gap-3 border border-amber-300/35 bg-amber-300/10 px-3 py-2 text-sm text-amber-900 dark:text-amber-100">
           <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />