RFC 0007: Pluggable scheduler seam in gateway

[amittell]

This RFC proposes a narrow plugin-SDK seam that lets an external scheduler plugin own scheduled-job dispatch while the gateway keeps owning heartbeats and run-state ingestion. The built-in cron stays the default; when a scheduler plugin declares owns: "scheduled-jobs", the gateway disables its in-process cron at startup and routes job registration through the plugin runtime.

Why this RFC

Operators with workflows that need durability, retries, approvals, multi-step chains, or full run history reach for external schedulers (notably openclaw-scheduler, a SQLite-backed sibling service). Today those tools can only talk to the gateway through the public HTTP surface and cannot register scheduled work that the gateway considers first-class. The seam proposed here would let the same external runtime become the canonical scheduler so its runs surface in gateway status, hooks, and transcript mirroring.

Scope

• Three runtime functions: registerScheduledJob, cancelScheduledJob, listScheduledJobs.
• One discovery field: owns: "scheduled-jobs" on kind: scheduler manifests.
• Three run-state event shapes: onStart, onComplete, onError.
• Heartbeats stay in core, not behind this seam.
• No new compiled dependencies in the gateway.

Existence proof

The consumer side is already running. openclaw-scheduler has been deployed on two gateways (mac-mini.lan and rh-bot.lan) for several weeks, talking to OpenClaw only through the public HTTP surface. The skill is listed on ClawHub as durable-scheduler@1.0.0. What's missing is the seam.

If the shape proposed here is accepted, I'll carry the reference implementation as a follow-up PR against openclaw/openclaw. Drafting it now without an accepted seam shape would mean rewriting it against whatever the final contract looks like, which is why I'm leading with the RFC.

Notes

• A diagram of the discovery flow will go under rfcs/0007/ in a follow-up revision once the seam shape is settled.
• Draft because the runtime contract is the right place to take feedback before any code lands. The two remaining unresolved questions in the RFC body (whether cancelScheduledJob may be optional, and whether docs/tools consume listScheduledJobs directly or stay behind cron.list/cron.status) are explicit requests for maintainer input; the heartbeat-ownership and direct-HTTP-migration questions are now folded into decided text.

[clawsweeper]

Codex review: found issues before merge. Reviewed June 14, 2026, 12:44 AM ET / 04:44 UTC.

Summary
The branch adds rfcs/0008-pluggable-scheduler.md, a draft RFC proposing a plugin-SDK scheduler ownership seam with scheduler manifest ownership, register/cancel/list runtime calls, and run-state ingestion events.

Reproducibility: not applicable. this is a design RFC rather than a bug report. The relevant check is source and lifecycle review, and current main does not already contain the proposed scheduler seam.

Review metrics: 3 noteworthy metrics.

• Diff Surface: 1 file added, 215 lines added, 0 deletions. The PR is design-only, so review should focus on RFC lifecycle and accepted-contract risk rather than runtime test output.
• Open Contract Decisions: 2 unresolved API questions. The RFC still asks maintainers to decide cancelScheduledJob optionality and whether list/status consumers should use runtime calls directly.
• Visible RFC ID Mismatch: File is 0008; PR title/body still say 0007. Reviewer-facing metadata should match the added RFC number before final acceptance or merge.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🦞 diamond lobster
Patch quality: 🧂 unranked krab
Result: blocked by patch quality or review findings.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Update the PR title/body so every visible identifier uses RFC 0008 and future assets point at rfcs/0008/.
• Keep the RFC unmerged while it is status: draft, or update accepted metadata only after maintainer approval and an implementation issue exist.
• Spell out scheduler ownership, fallback, list/cancel, and run-state trust semantics before treating the RFC as accepted.

Risk before merge

• [P2] Accepting the RFC would define a new plugin kind and ownership token that can disable built-in cron and route cron.* scheduled-job calls to plugin code, so existing cron fallback and upgrade behavior need explicit maintainer approval.
• [P1] Plugin-supplied run-state events would feed gateway status, hooks, and transcript-related surfaces; authorization, event validation, replay/deduplication, and failure isolation need to be settled before the design becomes accepted contract.
• [P1] The PR title/body still describe RFC 0007 while the branch adds RFC 0008, which can confuse reviewers and future asset references even though the file itself now points at rfcs/0008/.

Maintainer options:

1. Keep Draft Until Contract Signoff (recommended)
   Before merge, align visible RFC 0008 metadata and have maintainers record the scheduler ownership, fallback, cancel/list, and run-state trust decisions in the RFC.
2. Accept Direction With Explicit Runtime Gates
   Maintainers could accept the direction only if the RFC clearly states that implementation PRs must prove default cron compatibility, migration behavior, and plugin event trust before runtime code lands.
3. Pause If Core Plugin Ownership Is Too Broad
   If scheduler ownership should stay outside the core plugin SDK, leave this unmerged and keep external schedulers on the current HTTP or plugin-local path until a narrower API is proposed.

Next step before merge

• [P2] The remaining action is maintainer API/security approval plus PR metadata cleanup, not a safe automated repair lane.

Security
Needs attention: The diff is design-only, but accepting it would define a plugin-controlled scheduler and run-state boundary that needs maintainer security review before merge.

Review findings

• [P1] Keep draft RFCs out of the merge path — rfcs/0008-pluggable-scheduler.md:8-9
• [P1] Define scheduler ownership before acceptance — rfcs/0008-pluggable-scheduler.md:93-105
• [P1] Define run-state event trust before acceptance — rfcs/0008-pluggable-scheduler.md:128-140

Review details

Best possible solution:

Keep this as a draft discussion until maintainers settle the scheduler ownership, fallback, cancel/list, and run-state trust contract; then update visible 0008 metadata and accepted-RFC fields before merge if approved.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a design RFC rather than a bug report. The relevant check is source and lifecycle review, and current main does not already contain the proposed scheduler seam.

Is this the best way to solve the issue?

Unclear as a final solution; the RFC is a useful discussion path, but merge should wait until maintainers settle the plugin API, compatibility, and security boundary decisions.

Full review comments:

• [P1] Keep draft RFCs out of the merge path — rfcs/0008-pluggable-scheduler.md:8-9
  The repository lifecycle says draft RFCs should not merge; this file leaves status: draft and issue blank, so merging now would bypass the accepted-RFC flow. If maintainers accept the proposal, update the status and implementation issue before merge.
  Confidence: 0.93
• [P1] Define scheduler ownership before acceptance — rfcs/0008-pluggable-scheduler.md:93-105
  This routes cron.* calls to a scheduler plugin based on manifest ownership, but the accepted contract still needs explicit selection, authorization, competing-owner, and failure/fallback semantics before built-in cron can safely be disabled.
  Confidence: 0.86
• [P1] Define run-state event trust before acceptance — rfcs/0008-pluggable-scheduler.md:128-140
  Plugin-provided lifecycle events feed gateway status, hooks, and transcript-related surfaces, but the RFC does not yet specify validation, provenance, replay/deduplication, or failure-isolation rules for that event stream.
  Confidence: 0.84

Overall correctness: patch is incorrect
Overall confidence: 0.89

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against 3aa7d727383f.

Label changes

Label justifications:

• P3: This is a design RFC for an optional future plugin seam and does not change runtime behavior in this repository.
• merge-risk: 🚨 compatibility: The accepted design would change the future plugin SDK and cron ownership model, affecting scheduler fallback and upgrade behavior.
• merge-risk: 🚨 security-boundary: The accepted design would let scheduler plugins own scheduled-job dispatch and feed gateway run-state surfaces, which is a trust boundary needing explicit approval.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦞 diamond lobster and patch quality is 🧂 unranked krab.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The PR comments include redacted terminal output showing openclaw-scheduler running as peer services on two real gateways, which is sufficient proof for the RFC's existence-proof claim.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR comments include redacted terminal output showing openclaw-scheduler running as peer services on two real gateways, which is sufficient proof for the RFC's existence-proof claim.

Evidence reviewed

Security concerns:

• [medium] Scheduler plugins would own a gateway control path — rfcs/0008-pluggable-scheduler.md:128
  The RFC routes scheduled-job calls to a plugin and feeds plugin run-state events into gateway-visible surfaces, so authorization, event trust, and failure isolation need explicit design before acceptance.
  Confidence: 0.84

What I checked:

• Target AGENTS.md check: No AGENTS.md exists inside the target repository checkout, so no target-specific AGENTS policy was applied. (3aa7d727383f)
• PR file state: The PR head adds rfcs/0008-pluggable-scheduler.md with status: draft, a blank issue, scheduler ownership routing, runtime calls, run-state ingestion, and two unresolved API questions. (rfcs/0008-pluggable-scheduler.md:8, f84235890a3a)
• RFC lifecycle policy: README lifecycle text says new RFCs should not merge while still draft and accepted RFCs should set status: accepted plus an implementation issue before merge. (README.md:80, e366ea9825a4)
• Current-main implementation search: Current main has cron references in the QA scorecard RFC but no pluggable scheduler seam, scheduled-jobs ownership token, or SchedulerHostRuntime. (3aa7d727383f)
• Contributor proof: The PR discussion includes redacted terminal output showing openclaw-scheduler running as launchd-supervised peer services on two gateways, supporting the RFC's existence-proof claim. (f84235890a3a)
• Diff verification: The PR diff is one added RFC file and git diff --check reported no whitespace errors. (f84235890a3a)

Likely related people:

• kevinlin-openai: Introduced the current RFC template and lifecycle wording that governs draft status, accepted status, issue metadata, and merge timing. (role: RFC process and template contributor; confidence: high; commits: f4fdf38f4717, bbb4058da234, e366ea9825a4; files: README.md, rfcs/0000-template.md)
• Dallin Romney: Added the accepted RFC 0007 content and sidecar directory on main, then clarified the repository sidecar layout in the README. (role: recent RFC numbering and sidecar contributor; confidence: high; commits: 0cee55564c0c, 3aa7d727383f; files: rfcs/0007-e2e-qa-lab-scorecard-consolidation.md, rfcs/0007/implementation-plan.md, README.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[amittell]

@clawsweeper re-review

The previous review at 2026-06-01T02:55Z failed before completion ('Review failed before ClawSweeper could summarize the requested change'). Asking for a fresh attempt.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/26842961201
• Updated: 2026-06-02T19:31:44.348Z

[amittell]

@clawsweeper re-review

Addressed P1: renumbered to rfcs/0007-pluggable-scheduler.md in commit 6257777 to resolve the id collision with rfcs/0006-feeds.md on main. The in-document rfcs/0006/ asset reference is also updated to rfcs/0007/. PR title updated to match.

P2 (plugin contract / maintainer signoff) is by-design — that's the RFC purpose, not a code issue.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27110674859
• Updated: 2026-06-08T01:21:58.590Z

[amittell]

On the "claimed external scheduler deployment" P1 proof gap:

Captured live deployment evidence from both gateways the RFC references. Both hosts are launchd-supervised; openclaw-scheduler runs as a separate service under a separate Label from the OpenClaw gateway, with a multi-day uptime, talking to the gateway only through the public HTTP / WebSocket surface (no shared in-process code).

$ ssh user@gateway-host 'launchctl print "gui/$(id -u)/ai.openclaw.scheduler" | grep -E "state|pid =|program ="'
        state = running
        program = /usr/bin/caffeinate
        pid = <scheduler-pid>
                state = active
                state = active

$ ssh user@gateway-host 'ps -eo pid,etime,command | grep -E "openclaw-scheduler/(dispatcher|inbox-consumer)" | grep -v grep'
<pid> 01-00:17:34 /opt/homebrew/bin/node --no-warnings ~/.openclaw/packages/openclaw-scheduler/node_modules/openclaw-scheduler/dispatcher.js
<pid> 01-00:17:34 /usr/bin/caffeinate -i /opt/homebrew/bin/node --no-warnings ~/.openclaw/packages/openclaw-scheduler/node_modules/openclaw-scheduler/dispatcher.js

$ ssh user@second-gateway-host 'launchctl print "gui/$(id -u)/ai.openclaw.scheduler" | grep -E "state|pid =|program ="'
        state = running
        program = /usr/bin/caffeinate
        pid = <scheduler-pid>
                state = active
                state = active

Observed:

• Two distinct gateways each run a separate ai.openclaw.scheduler launchd service alongside their ai.openclaw.gateway service.
• The dispatcher process is the published openclaw-scheduler npm package (packages/openclaw-scheduler/...dispatcher.js), running as a peer service, not in-process code.
• Uptime on the captured host is 1 day 17 minutes (multi-day continuous operation).
• The scheduler integrates with the gateway only through HTTP/WebSocket — there is no shared in-process code path — which is the exact pattern the RFC proposes formalizing through the plugin-SDK seam.

This is the consumer-side artifact the RFC's "existence proof" claim refers to. The RFC's purpose is to give that already-shipping out-of-process scheduler a first-class plugin-SDK seam so its scheduled runs surface in gateway status, hooks, and transcript mirroring; today they have to bridge through the public HTTP cron surface.

On P1 #1 ("blesses new plugin kind / future migration concern"): that's the explicit RFC purpose. The proposal is intentionally additive — built-in cron stays the default; the plugin kind only engages when an external scheduler plugin registers itself.

On P1 #3 ("API-design questions intentionally open"): all four open questions in the RFC are flagged in an "Unresolved questions" section so a maintainer decision can land before any implementation follows. That's the correct shape for an RFC discussion vehicle, not a blocker on the proposal itself.

[amittell]

@clawsweeper re-review

The requested redacted live deployment proof was added in #5 (comment). Please re-review against the current PR head and the added proof.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27110506079
• Updated: 2026-06-08T01:15:31.687Z

[amittell]

Status update (2026-06-09): pushed 752a3d9 addressing the P2 rank-up move.

rfcs/0007-pluggable-scheduler.md frontmatter now includes:

status: draft
issue:

per the 2026-06-07 review. last_updated bumped to today to match.

The maintainer questions on the plugin contract (ownership token, fallback semantics, runtime API shape) are still open by design for an RFC; will respond inline as soon as a maintainer indicates a direction.

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27235041080
• Updated: 2026-06-09T20:57:05.968Z

[amittell]

Status update (2026-06-12): pushed 82c24c6 narrowing the maintainer ask.

Two of the four unresolved questions were already answered by the doc body, so they are now decided text instead of open questions:

• Heartbeats stay in core (decided for v1; a future job-grade-durability heartbeat would be a new owns token in a follow-up RFC, not a widening of this seam).
• Migration for direct-HTTP operators is doctor-finding territory in a follow-up RFC (folded into Non-Goals).

What's left for maintainers is exactly two contract questions: (1) may cancelScheduledJob be optional with unregister-on-next-startup fallback, or required to match registerScheduledJob's live handle; (2) do docs/tools consume listScheduledJobs directly, or stay behind cron.list/cron.status so scheduler storage remains private. Also fixed the stale rfcs/0006/ reference in the PR description left over from the renumber.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Failed
• Detail: The targeted re-review did not finish cleanly. Check the workflow run for details.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27396568708
• Updated: 2026-06-12T05:31:52.942Z