feat(plugins): add cron reconciliation lifecycle hook by steipete · Pull Request #104191 · openclaw/openclaw

steipete · 2026-07-11T05:28:55Z

Related: #103736 (the separate hot-reload publication/atomicity issue is not changed by this PR).

What Problem This Solves

Plugins that project OpenClaw cron jobs into an external scheduler have no authoritative lifecycle point after the Gateway has loaded durable cron state and reconciled exit watchers. gateway_start can run too early, while cron_changed is a coalescible change hint rather than a complete-state baseline.

Why This Change Was Made

This adds a typed cron_reconciled observation hook after scheduler startup and every scheduler replacement on config reload. The event exposes only the reconciliation reason and effective enabled state; plugins read the exact reconciled scheduler through ctx.getCron(). Generation guards, serialized delivery, and shutdown invalidation suppress stale callbacks without introducing retries, durability, or plugin-only replay.

User Impact

Plugin authors can reliably rebuild a complete external cron projection after Gateway startup or scheduler replacement. Disabled cron emits enabled: false, allowing adapters to clear stale external wakes, while cron_changed remains available for low-latency incremental hints.

Evidence

Runtime hook head f2976f273c9648010fcde3ed5ff7161c409bfe36: 141 focused gateway/plugin test executions and pnpm plugin-sdk:api:check passed on Blacksmith Testbox tbx_01kx7tqqvxah2ms4g68ek1d7pp (Actions run).
SDK export-budget fix: all 10 plugin-sdk-surface-report tests and pnpm plugin-sdk:api:check passed on Blacksmith Testbox tbx_01kx7vcdpjxe3w3vdc5j8g1wk1 (Actions run).
Final rebased head 30fdbfa92b1c630f393a000e2cc7bfd2823abac2; the intervening origin/main files are outside this PR's gateway/plugin/SDK surface. Exact-head hosted CI is the landing gate.
Pre-rebase full proof on the same patch: pnpm check:changed, pnpm check:docs, and pnpm build passed; the build included the Plugin SDK export check.
Exact rebased head docs formatting, Markdown lint, and MDX validation passed. The global link audit currently reports six missing IDENTITY/USER template routes introduced on origin/main; those paths are outside this PR diff.
git diff --check passed.
Fresh GPT-5.5 autoreview: no accepted or actionable findings.

AI-assisted: yes; maintainer-directed and manually audited.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b93299d02c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-07-11T05:35:21Z

        },
-        cron: runtimeState.cronState.cron,
+        cronState: runtimeState.cronState,
+        cronReconciliation,


Gate startup reconciliation on plugin readiness

When the gateway is started in deferred sidecar mode (the CLI selects this for OPENCLAW_SKIP_CHANNELS/OPENCLAW_SKIP_PROVIDERS), startGatewayPostAttachRuntime returns before plugin sidecars finish loading, but this post-ready timer can still start cron and complete cron_reconciled after only 250ms. If plugin loading takes longer, getGlobalHookRunner() has no newly loaded cron_reconciled handlers yet, so an external scheduler plugin misses its only startup baseline until a later cron reload or gateway restart.

Useful? React with 👍 / 👎.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f2976f273c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-07-11T05:42:01Z

+            if (params.isClosing() || generation !== lifecycleGeneration) {
+              return;
+            }
+            await params.runHook(event, {


Add a timeout for serialized cron_reconciled hooks

When a cron_reconciled handler has no configured hooks.timeoutMs and its promise never settles (for example an external scheduler RPC hangs), this await leaves dispatchTail unresolved, so every later startup/reload reconciliation is queued behind it and no plugin receives the fresh cron baseline until the gateway restarts. The hook runner only applies default timeouts to named hooks in DEFAULT_VOID_HOOK_TIMEOUT_MS_BY_HOOK, and this new hook is not one of them, so the serialized lifecycle needs its own bounded timeout or default hook budget.

Useful? React with 👍 / 👎.

clawsweeper · 2026-07-11T05:43:46Z

Codex review: stale review; fresh review needed.

Summary
The latest durable ClawSweeper review was for head f2976f273c9648010fcde3ed5ff7161c409bfe36, but the PR head is now 30fdbfa92b1c630f393a000e2cc7bfd2823abac2. Its old verdict and PR readiness labels are no longer current.

Next step
Run or wait for a fresh ClawSweeper review on the current PR head.

Review history (1 earlier review cycle)

reviewed 2026-07-11T05:49:22.611Z sha f2976f2 :: needs real behavior proof before merge. :: [P2] Gate startup reconciliation on plugin readiness | [P2] Bound serialized cron reconciliation hooks

steipete · 2026-07-11T06:04:29Z

Land-ready at exact head 30fdbfa92b1c630f393a000e2cc7bfd2823abac2.

The typed cron_reconciled hook now fires only after the Gateway cron scheduler and exit watchers reach a complete startup/reload state. Generation invalidation, shutdown suppression, serialized delivery, disabled-cron reporting, the public SDK surface, and docs are covered. Native review artifacts validate as READY FOR /prepare-pr with zero findings.

Proof:

Exact-head CI run 29141941312, attempt 2: success. The first attempt's sole failure was the unrelated src/agents/subagent-orphan-recovery.restart-integration.test.ts; its single-job rerun 86517219141 passed without a code change.
Blacksmith Testbox run 29141439667: 141 focused gateway/plugin test executions and pnpm plugin-sdk:api:check passed on the runtime hook head.
Blacksmith Testbox run 29141737063: all 10 plugin-sdk-surface-report tests and pnpm plugin-sdk:api:check passed with the SDK export-budget fix.
Full patch proof before the final unrelated main sync: pnpm check:changed, pnpm check:docs, pnpm build, and git diff --check passed.
Fresh GPT-5.5 autoreview after the budget fix: no accepted/actionable findings.
scripts/pr review-validate-artifacts 104191: passed at the exact PR head.

Known proof gaps: none for the core lifecycle contract. An external scheduler adapter is intentionally follow-up work; #103736 remains the separate reload publication/atomicity issue.

steipete · 2026-07-11T06:05:16Z

Merged via squash.

Prepared head SHA: 30fdbfa92b1c630f393a000e2cc7bfd2823abac2
Landed commit: 49b58288d3eb63536b2e11aa5616c902b85089b0

* feat(plugins): add cron reconciliation lifecycle hook * chore(plugin-sdk): refresh api baseline * fix(plugin-sdk): update public export budget

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime size: L maintainer Maintainer-authored PR labels Jul 11, 2026

chatgpt-codex-connector Bot reviewed Jul 11, 2026

View reviewed changes

steipete force-pushed the codex/cron-reconciled-hook branch from b93299d to f2976f2 Compare July 11, 2026 05:37

chatgpt-codex-connector Bot reviewed Jul 11, 2026

View reviewed changes

clawsweeper Bot mentioned this pull request Jul 11, 2026

[Feature]: Add a post-start cron reconciliation lifecycle hook #104082

Closed

steipete added 3 commits July 11, 2026 01:48

feat(plugins): add cron reconciliation lifecycle hook

920e296

chore(plugin-sdk): refresh api baseline

31941ff

fix(plugin-sdk): update public export budget

30fdbfa

steipete force-pushed the codex/cron-reconciled-hook branch from f2976f2 to 30fdbfa Compare July 11, 2026 05:54

openclaw-barnacle Bot added the scripts Repository scripts label Jul 11, 2026

steipete merged commit 49b5828 into main Jul 11, 2026
172 of 177 checks passed

steipete deleted the codex/cron-reconciled-hook branch July 11, 2026 06:05

steipete mentioned this pull request Jul 11, 2026

docs(plugins): document safe external cron projection #104227

Merged

github-actions Bot mentioned this pull request Jul 11, 2026

📡 Upstream Digest — 2026-07-11 07:42 UTC curtismercier/openclaw-mods#1258

Open

steipete mentioned this pull request Jul 11, 2026

[Bug]: Superseded cron reconciliation blocks newer scheduler projections #104363

Closed

clawsweeper Bot mentioned this pull request Jul 11, 2026

fix(cron): abort superseded reconciliation hooks #104368

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(plugins): add cron reconciliation lifecycle hook#104191

feat(plugins): add cron reconciliation lifecycle hook#104191
steipete merged 3 commits into
mainfrom
codex/cron-reconciled-hook

steipete commented Jul 11, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 11, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 11, 2026

Uh oh!

clawsweeper Bot commented Jul 11, 2026 •

edited

Loading

Uh oh!

steipete commented Jul 11, 2026

Uh oh!

Uh oh!

steipete commented Jul 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

steipete commented Jul 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 11, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 11, 2026

Choose a reason for hiding this comment

Uh oh!

clawsweeper Bot commented Jul 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steipete commented Jul 11, 2026

Uh oh!

Uh oh!

steipete commented Jul 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

steipete commented Jul 11, 2026 •

edited

Loading

clawsweeper Bot commented Jul 11, 2026 •

edited

Loading