fix(authz): give the convergence-stall escape hatch an executor (BLO-21947)

[allyblockcast]

Thinking Path

• Paperclip is the open source app people use to manage AI agents for work
• The issue-monitor subsystem lets an agent schedule a timed re-check ("wake") on an issue, and the BLO-18294 convergence guard stops re-arming a monitor once N consecutive re-checks fail to narrow what the issue is waiting on — so polling loops cannot burn budget forever
• That guard deliberately bars the assignee from granting itself a fresh budget, on the stated rule that "a non-assignee actor must make that re-arm decision"
• But no non-assignee could execute that decision: isLapsedMonitorRearmPatch — the sole feeder of managerMonitorRearmAuthorized — admitted only monitor status: "triggered", while a stall produces status: "cleared" / clearReason: "convergence_stalled"
• So once the guard tripped, the monitor was permanently unarmable by anyone in the agent fleet: the assignee barred by the guard, everyone else barred by the route gate. The escape hatch the guard's design depends on had no executor
• This pull request admits that second lapse shape at the route gate, so a manager-chain actor can perform the re-arm the service layer is already written to accept
• The benefit is that a stalled issue stops being a silent dead end recoverable only by a human board user

Linked Issues or Issue Description

Refs BLO-21947 — "Non-assignee actors get 403 on both run-cancel and issue-monitor management — the designated convergence-stall recovery actor has no permission to recover." This PR closes its monitor half only; see Risks for what is deliberately left open.

Refs BLO-18294 (the convergence guard whose escape hatch this makes executable) and BLO-23082 (same gap, reached from productivity-review adjudication).

Related PRs found while searching (none overlap this predicate — verified by diffing each):

• feat(authz): scoped stranded-execution recovery for managing agents (BLO-21947) #1229 (kkroo) — the original stranded-execution recovery branch. Carries an alternative issue:recover_monitor design that was superseded by BLO-22860's managerMonitorRearmAuthorized on master; currently dirty, 209 behind. Deliberately not chained on, per the CEO ruling on BLO-21947.
• feat(authz): scoped stranded-execution recovery lever for a managing agent (BLO-21947) #1161 — earlier attempt at the same lever, CONFLICTING.
• test(issues): pin BLO-24149 stranded-issue monitor re-arm, add runbook #1343 — pins the triggered re-arm case (BLO-24149) in the same test file; complementary, does not touch this predicate.
• fix: recover issue monitors stuck triggered past timeoutAt with null nextCheckAt #1326, fix(recovery): bound how long a lapsed monitor counts as a live wake path (BLO-24782) #1330 — adjacent monitor-recovery work in heartbeat.ts / recovery/service.ts; neither touches isLapsedMonitorRearmPatch.

What Changed

• server/src/routes/issues.ts — isLapsedMonitorRearmPatch now admits a second lapse shape: a monitor cleared with clearReason: "convergence_stalled", alongside the existing triggered. Extracted to a named isRecoverableLapsedMonitor with the rationale inline.
• server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts — 6 new cases: the manager-chain re-arm of a convergence-stalled monitor succeeds; an actor without manager-chain still gets 403; and an it.each pinning that monitors cleared for done / invalid_status / invalid_assignee / bounds_exhausted stay refused.

No change to the service layer: resetConvergenceAfterStalledClear and sameAssigneeResetAfterPriorStall already implement the recovery and the assignee bar. This PR only makes them reachable.

Verification

npx tsc --noEmit — clean.

npx vitest run server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts \
  --no-file-parallelism --maxWorkers=1
  → Test Files 1 passed | Tests 216 passed (was 210; 6 new)

npx vitest run server/src/__tests__/issue-monitor-convergence-guard.test.ts \
                server/src/__tests__/issue-execution-policy-routes.test.ts \
  --no-file-parallelism --maxWorkers=1
  → Test Files 2 passed | Tests 68 passed

Control run — production change reverted, new tests kept:

× lets a manager-chain agent re-arm a monitor the convergence guard cleared (BLO-21947)
AssertionError: {"error":"Issue is outside this actor's authorization boundary (grant)",
  "details":{"reason":"deny_missing_grant","boundary":"grant"}}: expected 403 to be 200

That is byte-for-byte the 403 BLO-21947 documents, so the fix is load-bearing rather than the test passing incidentally. The three negative cases pass in both arms, as they should.

CI: General tests (server) covers the new cases.

Risks

Low, and the blast radius is bounded by three unchanged gates. The re-arm path still requires a single-key body, a normalized policy carrying a monitor and no stages / reviewPreset / authorizationPolicy, and an allow_manager_chain decision. This PR widens only which monitor state qualifies.

• Scope creep into a general cross-assignee policy write — the main hazard, since this path deliberately skips the ordinary mutation boundary. Mitigated by admitting exactly one additional clearReason; the it.each fails if anyone later broadens it to "any cleared monitor".
• Deliberately NOT admitting issue status blocked. The guard force-sets the issue to blocked, so admitting it here looks required — but it would be unreachable code: issueAllowsMonitor permits monitors only on in_progress/in_review, so monitorClearReasonForIssue returns invalid_status and the service throws MONITOR_INVALID_MESSAGE on an explicit update, with resetConvergenceAfterStalledClear itself gated on !invalidReason. Recovery is therefore a two-step: return the issue to active work, then have a non-assignee re-arm. Called out because the one-step reading is the natural mistake.
• The assignee bar is unchanged — sameAssigneeResetAfterPriorStall still throws, so this does not let a stalled assignee self-serve a fresh budget.
• Out of scope: the cancel half of BLO-21947 is untouched. POST /heartbeat-runs/:runId/cancel remains assertBoard, and there is no run:recover_stranded or requireUndispatched CAS on master (re-verified this run). That follows as a separate PR; this one does not claim to close BLO-21947.

Model Used

Claude Opus 4.5 (claude-opus-5[1m]) via Claude Code, running as the Paperclip CTO agent with extended thinking and tool use (repository read/edit, git, gh, local vitest/tsc execution). All test output and the control run quoted above were executed in this run, not predicted.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template
• I have run tests locally and they pass
• I have added or updated tests where applicable
• If this change affects the UI, I have included before/after screenshots — n/a, server-side authorization only
• I have updated relevant documentation to reflect my changes — the rationale, including why blocked is deliberately excluded, is inline at the predicate
• I have considered and documented any risks above
• All Paperclip CI gates are green — in flight at time of writing
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups — pending review

🤖 Generated with Claude Code

[allyblockcast]

🔗 Paperclip issue: BLO-18294
🔗 Paperclip issue: BLO-21947

[allyblockcast]

🔗 Paperclip issue: BLO-18294
🔗 Paperclip issue: BLO-21947

[allyblockcast]

Hey @allyblockcast[bot]! Before this PR can be reviewed, a few things need attention:

Missing or incomplete:

• Missing section: ## Thinking Path
• Missing section: ## What Changed
• Missing section: ## Risks
• Missing section: ## Model Used
• Add the dedup-search checkbox to your PR description and check it once you have searched the GitHub PR list for similar PRs. See the PR template at .github/PULL_REQUEST_TEMPLATE.md and CONTRIBUTING.md → "Before You Start: Search First".

Once updated, push a new commit and these checks will re-run automatically.

— commitperclip

[allyblockcast]

@ally please review at head 730d3ee0 — all 19 checks are green and mergeable_state is clean, so nothing mechanical is gating this. It has never been reviewed at any head (both surfaces empty), and it is an authorization-boundary change, so I do not want it landing unreviewed.

What it does. Relaxes the route gate on PATCH /issues/:id monitor management so a non-assignee manager can re-arm a monitor that the convergence guard force-cleared. The service layer already implements this recovery (resetConvergenceAfterStalledClear, sameAssigneeResetAfterPriorStall in issue-execution-policy.ts); the route gate simply never let a non-assignee through. This connects an existing capability rather than adding one.

Please focus on:

1. Scope of the relaxation. Only convergence_stalled is admitted; done / invalid_status / invalid_assignee / bounds_exhausted must stay refused (pinned by an it.each). Is that enumeration actually exhaustive against the clear-reason union, or can a new reason default into the allow path?
2. Gate composition. The single-key, monitor-only-normalized-policy, and allow_manager_chain gates are meant to be untouched and still binding. Please confirm the new branch cannot be reached without all three.
3. Self-serve escape. sameAssigneeResetAfterPriorStall is what stops a stalled assignee granting itself a fresh budget. Confirm the route change does not create a path around it (e.g. via manager-chain where the actor is also the assignee).
4. Dead code. An earlier revision of this design admitted blocked status at the gate, which would have been unreachable (monitorClearReasonForIssue → invalid_status throws first). I removed that. Please check nothing unreachable is left.

Tests: issue-agent-mutation-ownership-routes.test.ts 216 passed (6 new). Control with the route change reverted fails the new positive case with the exact deny_missing_grant 403 this issue documents, so the change is load-bearing.