Codex review: needs changes before merge.

Summary
The PR adds a centralized heartbeat wake cooldown helper/bookkeeping with regression tests, updates the changelog, exposes a new plugin-sdk/tool-descriptors subpath, updates the SDK API hash, and adjusts several tests/fixtures.

Reproducibility: yes. Current main is source-reproducible by sending repeated targeted exec-event wakes inside nextDueMs; the remaining PR regressions are source-reproducible by sending hook:wake or background-task-blocked after a prior heartbeat run.

Next step before merge
The remaining blockers are narrow mechanical repairs on the PR branch: fix wake-policy exceptions/tests and add the missing SDK subpath documentation or remove the unintended export.

Security
Cleared: No concrete security or supply-chain regression found; the diff adds no dependencies, workflows, permissions, secret handling, or downloaded code.

Review findings

• [P2] Preserve hook wake-now delivery — src/infra/heartbeat-cooldown.ts:70
• [P2] Keep blocked task follow-ups immediate — src/infra/heartbeat-cooldown.ts:70
• [P3] Document the tool-descriptors SDK subpath — package.json:1233-1235

Thanks for the review. Pushed 52d41262c1 addressing both findings.

P2-1: Preserve immediate wake-now paths

You're right — the previous gate caught wake (from openclaw system event --mode now) and background-task (from task-registry.ts:1079) along with the loop-prone reasons. Both are documented as immediate.

Fix: explicit IMMEDIATE_WAKE_REASONS allowlist in heartbeat-cooldown.ts:

const IMMEDIATE_WAKE_REASONS: ReadonlySet<string> = new Set([
  "manual",
  "wake",
  "background-task",
]);

Matched on the raw reason string, not on HeartbeatReasonKind. That distinction matters because acp:spawn:* also classifies as kind wake via heartbeat-reason.ts, but those are agent-emitted spawn updates that can feedback-loop and must remain gated. The allowlist is exact-string so this stays unambiguous.

The flood guard still applies as a backstop to wake and background-task (could imagine a buggy task that completion-storms the heartbeat); only manual is fully exempt since it's user-pressed.

Tests added covering:

• wake and background-task not deferred within nextDueMs
• acp:spawn:stream STILL deferred (verifies the kind/raw distinction)
• Flood guard still backstops wake and background-task
• manual exempt even during a real flood

P2-2: Don't poison cooldown on retryable busy skip

Confirmed by inspection — moved recordRunBookkeeping to AFTER runOnce in both branches, conditional on non-retryable result. The retryable busy branch now returns without recording; the wake-layer retry will see lastRunStartedAtMs unchanged and proceed.

Throws also count as terminal attempts (so a consistently-throwing reason doesn't tight-loop on retries).

New regression test:

it("retryable busy skip does not poison the cooldown for the next retry", async () => {
  let attempt = 0;
  const runSpy = vi.fn().mockImplementation(async () => {
    attempt += 1;
    if (attempt === 1) {
      return { status: "skipped", reason: HEARTBEAT_SKIP_REQUESTS_IN_FLIGHT } as const;
    }
    return { status: "ran", durationMs: 1 } as const;
  });
  // ... 1st wake: requests-in-flight. After 1.5s wake-layer retry,
  // 2nd wake must reach runOnce — not be deferred as 'not-due'/'min-spacing'.
  expect(runSpy).toHaveBeenCalledTimes(2);
});

Fails on the prior commit. Passes on 52d41262c1.

Acceptance criteria checklist

• pnpm test src/infra/heartbeat-cooldown.test.ts src/infra/heartbeat-runner.scheduler.test.ts — 66 pass (49 cooldown + 17 scheduler)
• pnpm test src/tasks/task-registry*.test.ts src/cron/service*.test.ts — 79 pass
• Full heartbeat suite (ls src/infra/heartbeat*.test.ts | xargs pnpm test) — 148 pass
• pnpm exec oxfmt --check --threads=1 src/infra/heartbeat-cooldown.ts src/infra/heartbeat-cooldown.test.ts src/infra/heartbeat-runner.ts src/infra/heartbeat-runner.scheduler.test.ts CHANGELOG.md — clean
• pnpm check:changed — exit 0 (typecheck core + tests, lint core, all guards green)

CHANGELOG entry — happy to add one if maintainers want it as part of this PR; the AGENTS guidance suggests pure infra/test fixes can skip but this one has user-visible cadence implications.

Two updates:

Live verification on real gateway

Built 52d41262c1, started gateway with --verbose, monitored for 3 minutes with the same every: "30m" heartbeat config that previously produced ~10s runaway loops.

Pre-fix baseline (same workstation, earlier tonight): 5+ heartbeat runs in 3 minutes, all messageChannel=heartbeat, ~60s gap between completions and next start.

Post-fix:

• T+0–60s: 0 runs
• T+120s: 1 run started, but messageChannel=unknown (external dispatch — webchat/telegram), NOT a heartbeat
• T+180s: that run completed (38s), no new runs

Heartbeat runaway is gone in the real gateway. The cooldown gate is holding exec-event and friends as expected, and wake/background-task paths still flow through (verified via the new unit tests).

CI failure on Scan changed paths (precise) is a false attribution

Run 25204141642 / job 73901114636 flagged extensions/voice-call/src/providers/twilio/api.ts:60 for SSRF. That file is not in this PR.

$ git diff --name-only $(git merge-base origin/main HEAD)..HEAD
src/infra/heartbeat-cooldown.test.ts
src/infra/heartbeat-cooldown.ts
src/infra/heartbeat-runner.scheduler.test.ts
src/infra/heartbeat-runner.ts

The OpenGrep step uses OPENCLAW_OPENGREP_BASE_REF: e8f9c3e6dedc...HEAD, but e8f9c3e6dedc is downstream of this PR's merge-base (76930da7ebc7). The voice-call file landed on main in commit 97d42a9614 (fix(voice-call): retry twilio answered updates), well outside this PR.

The finding is real-but-unrelated — it's a pre-existing risk on main that the voice-call team should address (or nosem annotate if it's a false positive). Happy to file a separate issue if useful, but it shouldn't block merge of this PR.

CI failures here are inherited from main HEAD 0e8cb3d9 (the rebase target). The latest completed CI run on main (run 25216237781) failed with the exact same 9 jobs:

• check-lint
• check-test-types
• check-dependencies
• checks-node-core-runtime-infra
• checks-node-core-fast-support
• checks-node-agentic-gateway-core
• checks-node-agentic-cli
• check
• checks-node-core

Failing tests are in unrelated areas (whatsapp qrcode runtime dep, pairing-store, web-search-codex-config, model-pricing-cache, plugins-cli.install, etc.) — none touch heartbeat code on this PR. Will rebase again once main is green.

@obviyus — would you be open to reviewing? Heartbeat scheduler / cooldown-gate work in adjacent territory to your #75922 plugin-registry caching. Targets a separate runaway path on the same gateway-CPU-peg symptom cluster (#75703 / #75872 / #75707 / #75882).

Thanks @hexsprite for tracking this down and for the detailed repro/writeup. I rewrote the fix into a slightly larger maintainer-owned cleanup that keeps the root cause explicit: wake producers now declare typed source / intent, event-driven wakes go through the shared cooldown, wake-now paths stay immediate, and the deprecated plugin requestHeartbeatNow() API remains as a compatibility alias.

I preserved your credit in the replacement commit with:

Co-authored-by: Jordan Baker jbb@scryent.com

Replacement PR: #76086
Replacement commit: deba234

Closing this one in favor of #76086 so review/CI can continue on the maintainer branch.