RFC 0029: External Automation Deadlines and Schedule-Only Occurrences

[omarshahine]

Summary

This draft asks Automations, Plugin SDK, and host maintainers whether to standardize the remaining external deadline registrar contract. OpenClaw keeps ownership of jobs, schedules, occurrences, execution, and history. The host arranges compute availability from a reconciled projection; host activation cannot complete an Automation run.

Current implementation status

Refreshed on 2026-09-05 against OpenClaw main bdd75d44c561, with RFC repository main 967d9aa merged into this branch without rewriting published history.

• Already landed: cron_reconciled, cron_changed, exact scheduler access, and lifecycle cancellation. Supporting PRs #103647 and #104368 merged in July.
• Already documented: Safe external cron projection requires atomic, idempotent, durable replace-all acceptance and abort handling. Its example includes rereads, stale-attempt cancellation, retries, disabled-state clearing, and shutdown join.
• Still proposed: bounded generic registrar types, explicit acceptance outcomes and receipts, cross-process revision arbitration, already-due host policy, and recovery/readiness composition.
• Deferred: scheduleOnly with externally claimed and completed occurrences. Current main has neither a wake nor scheduleOnly cron payload.

The landed prerequisites do not complete this RFC.

Proposed decision

• Build phase 1 on the existing plugin-owned projection pattern, with no new public payload kind, Gateway method, config key, or SQLite column.
• Decide whether the generic typed registrar adds enough value beyond the documented host adapter.
• Keep experimental PR #119040 paused pending the ownership decision. Refreshing that branch does not approve its payload contract.
• Require complete owner, authorization, admission, acknowledgement, replay, history, catch-up, one-shot, delivery, and client-compatibility semantics before externally completed occurrences can ship.

Relationship to RFC #5

RFC #5 now proposes per-job external shell/command dispatch while preserving OpenClaw's canonical jobs, admission, and history. This refresh corrects the older description of an external canonical scheduler.

Phase-one deadline projection and external payload execution remain distinct. Any future scheduleOnly protocol must converge with RFC #5 on one owner, admission, fencing, receipt, and history contract. Neither draft claims maintainer acceptance of that future contract.

Validation

• Audited current cron payload types, plugin hook context, and safe projection documentation.
• Compared RFC docs: propose an external Automations dispatch backend #5 at dc1519a51b4e and reviewed the existing feedback on this PR.
• Verified all seven required sections, draft metadata with an empty implementation issue, one-paragraph Summary, balanced code fences, punctuation, and git diff --check.
• Documentation-only change; no runtime behavior is added or claimed.

Outstanding acceptance gates

The required maintainer-discussion thread is not linked in this draft or PR. Maintainers still need to decide the registrar scope and future relationship to RFC #5. Acceptance and an implementation issue are required before changing the RFC status or merging it. This refresh leaves the RFC open and draft.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 5, 2026, 1:14 PM ET / 17:14 UTC.

ClawSweeper review

What this changes

Adds a draft RFC for projecting Automation deadlines to managed hosts while deferring externally completed occurrences.

Merge readiness

⛔ Blocked before merge - 5 items remain

Keep open: the proposed registrar contract is not present on the target default branch. The refresh addresses the prior overlap concern, but maintainer acceptance remains outstanding.

Priority: P3
Reviewed head: a4c616d7e242e0fb6dc71d423d660e4b519650cc
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The proposal is coherent and has no actionable patch defect; the overall rating is limited by the unsatisfied path-scoped external-PR proof gate.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The captured body supplies document audits and static validation only, and this RFC has no production implementation to exercise. Because rfcs/ is outside the review's docs/-only exemption, an explicit proof override is appropriate before merge; implementing the future protocol should not be required for design review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The captured body supplies document audits and static validation only, and this RFC has no production implementation to exercise. Because rfcs/ is outside the review's docs/-only exemption, an explicit proof override is appropriate before merge; implementing the future protocol should not be required for design review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	10 items	Complete introduced document inspected: Read all 711 lines. The branch adds one draft Markdown proposal, including normative registration semantics, phased implementation, compatibility safeguards, and unresolved acceptance questions; it introduces no executable implementation. Repository acceptance contract: README requires a maintainer-discussion thread, acceptance, an implementation issue, and accepted frontmatter before merging. The RFC explicitly acknowledges these outstanding gates at lines 709–711. Default-branch necessity check: The default-branch inventory lacks this RFC. Searches for deadline, registrar, scheduleOnly, reconciliation hooks, and external scheduling found no equivalent registrar proposal; the matches concern unrelated approval or localization deadlines.
Findings	None	None.
Security	None	None.

How this fits together

This repository records OpenClaw design proposals. The proposed registrar receives reconciled scheduler deadlines and arranges host compute availability, while OpenClaw retains responsibility for executing and recording Automation runs.

flowchart TD
  A[OpenClaw job schedules] --> B[Reconciled deadline inventory]
  B --> C[Plugin deadline registrar]
  C --> D{Host accepts replacement}
  D -->|Accepted| E[Durable deadline record]
  D -->|Rejected or superseded| C
  E --> F[Activate or retain compute]
  F --> G[OpenClaw executes and records occurrence]

Loading

Decision needed

Question	Recommendation
Should phase one standardize a generic deadline registrar beyond existing host adapters while leaving external occurrence completion deferred?	Advance a narrow phase one: Accept only deadline projection and registration semantics, with any future external-action protocol converging with #5.

Why: A permanent Plugin SDK contract and RFC acceptance require maintainer intent; the document's technical consistency cannot establish either.

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The captured body supplies document audits and static validation only, and this RFC has no production implementation to exercise. Because rfcs/ is outside the review's docs/-only exemption, an explicit proof override is appropriate before merge; implementing the future protocol should not be required for design review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - The value and permanent scope of a shared registrar API, beyond deployment-local adapters, remain unresolved.
• Resolve merge risk (P1) - GitHub connectivity prevented independent verification of the pinned upstream hook and lifecycle assertions.
• Complete next step (P2) - Link the maintainer-discussion thread, obtain a registrar-scope decision and explicit proof override, and only after acceptance add the implementation issue and accepted metadata before merging.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

None.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Standardize only a justified, bounded deadline-registration contract over existing hooks, keeping host storage deployment-owned and external occurrence completion deferred.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Standardize only a justified, bounded deadline-registration contract over existing hooks, keeping host storage deployment-owned and external occurrence completion deferred.

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

Not applicable: this PR proposes a future contract and does not report or implement a reproducible runtime fix.

Is this the best way to solve the issue?

Unclear: reusing existing projection hooks is a coherent direction, but maintainers must decide whether shared registrar types improve sufficiently on deployment-local adapters.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against 967d9aac7472.

Labels

Label justifications:

• P3: This is a design proposal with no runtime change or demonstrated urgent regression.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The captured body supplies document audits and static validation only, and this RFC has no production implementation to exercise. Because rfcs/ is outside the review's docs/-only exemption, an explicit proof override is appropriate before merge; implementing the future protocol should not be required for design review. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Complete introduced document inspected: Read all 711 lines. The branch adds one draft Markdown proposal, including normative registration semantics, phased implementation, compatibility safeguards, and unresolved acceptance questions; it introduces no executable implementation. (rfcs/0029-external-automation-deadlines.md:16, a4c616d7e242)
• Repository acceptance contract: README requires a maintainer-discussion thread, acceptance, an implementation issue, and accepted frontmatter before merging. The RFC explicitly acknowledges these outstanding gates at lines 709–711. (README.md:80, 967d9aac7472)
• Default-branch necessity check: The default-branch inventory lacks this RFC. Searches for deadline, registrar, scheduleOnly, reconciliation hooks, and external scheduling found no equivalent registrar proposal; the matches concern unrelated approval or localization deadlines. (967d9aac7472)
• Prior review concern addressed: The earlier review retained no findings and requested clarification of the scheduler proposal relationship. The current document distinguishes host activation from external action execution and requires any future external-completion protocol to converge with docs: propose an external Automations dispatch backend #5. (rfcs/0029-external-automation-deadlines.md:633, a4c616d7e242)
• Related proposal remains distinct: The supplied body of docs: propose an external Automations dispatch backend #5 limits its proposal to per-job external shell/command dispatch, preserves canonical OpenClaw admission and history, and explicitly separates this RFC's phase-one host-compute contract. That proposal remains open and unaccepted. (dc1519a51b4e)
• Explicit upstream dependency signal: The proposal relies on OpenClaw's cron_reconciled, cron_changed, captured scheduler access, and lifecycle cancellation contracts. Its linked upstream snapshot is therefore relevant evidence, rather than an inferred dependency. (rfcs/0029-external-automation-deadlines.md:212, a4c616d7e242)

Likely related people:

• Omar Shahine: Raw commit c876de6 adds rfcs/0026-automations-terminology.md:16 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: medium; commits: c876de6210bf; files: rfcs/0026-automations-terminology.md)
• kevinlin-openai: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Obtain an explicit proof override for this non-executable RFC rather than implementing the proposed runtime solely for proof.
• If supplying additional evidence, redact private information and update the PR body to trigger re-review; if needed, ask a maintainer to comment @clawsweeper re-review.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (1 earlier review cycle)

• reviewed 2026-08-04T18:01:58.722Z sha 7c4370b :: needs real behavior proof before merge. :: none