Make 'agents intentionally paused' a first-class state — deliberate token disable presented as fleet-wide outage (2026-08-16)

[don-petry]

Story

As a maintainer who sometimes takes the agent fleet offline deliberately (e.g. disabling CLAUDE_CODE_OAUTH_TOKEN to conserve quota),
I want "agents intentionally paused" to be a first-class, visible state,
so that a deliberate pause doesn't present as a mysterious fleet-wide outage — red dispatch runs on every event, silently stalled PRs, and hours of diagnosis to rediscover a decision the maintainer already made.

Problem — observed 2026-08-16→18

The maintainer disabled CLAUDE_CODE_OAUTH_TOKEN to limit token usage until the quota reset. Effects, none of which announced the cause:

• Every dev-lead / dispatch run failed at secrets evaluation ("Secret CLAUDE_CODE_OAUTH_TOKEN is required, but not provided") across all event types — indistinguishable from breakage, and red ❌s accumulated on every PR (e.g. 3 on fix: restore trunk from #1378 re-corruption — engine.sh 13 fns duplicated again, prompts stomped (#1485 recurrence) #1519).
• pr-review's confirmation tier could not run; PRs sat merge-ready with no signal (the [Phase 4] Detect merge-ready PRs stranded with no agent acting and no signal #1469 strand pattern, this time by design).
• The steering session spent a diagnostic arc ruling out quota, stub-sync regressions (chore: sync 4 org-standard workflow stub(s) from petry-projects/.github #1378), and reusable-ref resolution (feat: implement issue #1031 — fix(#844): plumb LSP_PILOT_ENABLED env + decouple capture from LSP wiring so the pilot A/B runs in CI #1034 class) before secret enumeration revealed the cause — knowledge only the maintainer had.
• Fleet monitor reports (petry-projects — workflow failures detected 2026-08-11 #1492-style) count these as failures, polluting the failure-rate signal for repos where the secret has simply never been provisioned.

Acceptance Criteria

1. A single explicit switch (suggestion: repo/org Actions variable AGENTS_PAUSED=true, since variables are visible where secrets are not) short-circuits agent dispatch workflows (dev-lead, pr-review trigger paths) as an early exit 0 step with a ::notice::agents paused by maintainer (AGENTS_PAUSED) — runs conclude green/neutral, not red.
2. When the required engine secret is absent and AGENTS_PAUSED is NOT set, the dispatch fails fast with an error that names the secret and links this issue — one clear line, not a secrets-evaluation stack error.
3. scripts/validate-engines.sh (already the engine-availability preflight) recognizes and reports the paused state distinctly from a misconfiguration.
4. The fleet monitor treats paused runs as healthy/neutral, not failures.
5. Docs: one paragraph in AGENTS.md on how to pause/resume the fleet deliberately.

Dev Notes

• The reusable declares CLAUDE_CODE_OAUTH_TOKEN: required: true, so the failure happens at caller secrets evaluation — before any step runs. The pause check must therefore live in the caller stubs (or the requirement relaxed to required: false with an in-run check) — an in-reusable check alone never executes. Mind the caller-stub-freeze baselines when touching stubs (caller_stub_freeze.sh --update).
• Related: [bug] Copilot engine fallback dead on classic PAT (ghp_) — Claude 429s misclassified as engine-error, escalating transient quota blips to needs-human #1495 (engine fallback dead + 429 misclassification) — same family of "engine availability presents as generic failure"; keep the two fixes consistent.

References

• Outage window: 2026-08-16 → 2026-08-19 (deliberate; quota conservation)
• Diagnostic trail: Formalize the agentic PR-interaction model (event-first, timers-as-backstop) — clear, repeatable, enforceable #1402 steering comments, fix: restore trunk from #1378 re-corruption — engine.sh 13 fns duplicated again, prompts stomped (#1485 recurrence) #1519 audit comment
• Related: [bug] Copilot engine fallback dead on classic PAT (ghp_) — Claude 429s misclassified as engine-error, escalating transient quota blips to needs-human #1495, [Phase 4] Detect merge-ready PRs stranded with no agent acting and no signal #1469, petry-projects — workflow failures detected 2026-08-11 #1492
• Epic: Formalize the agentic PR-interaction model (event-first, timers-as-backstop) — clear, repeatable, enforceable #1402