RFC 0029: External Automation Deadlines and Schedule-Only Occurrences

[omarshahine]

Summary

Adds a standalone RFC defining the ownership boundary between OpenClaw Automations and hosts that must keep compute available for scheduled deadlines.

The proposal keeps OpenClaw authoritative for jobs, schedules, occurrences, execution, run history, and outcomes. A plugin-owned registrar projects a bounded reconciled deadline snapshot to the host. Host activation does not create or complete an Automation run.

Why

PR openclaw/openclaw#119040 proposes a public wake payload that performs no payload work and records a successful run. That adds a persisted union member across Gateway schemas, tools, UI, macOS, and Android without defining an external owner or acknowledgement.

The RFC separates two requirements:

1. External deadline projection for host compute activation, using the existing cron_reconciled and cron_changed lifecycle.
2. A possible future scheduleOnly occurrence whose external owner must durably claim and complete the occurrence.

Proposed decision

• Select plugin-owned reconciled deadline projection for phase 1.
• Add no public payload kind, Gateway method, config key, or SQLite column in phase 1.
• Keep PR #119040 paused while the RFC is reviewed.
• Require a complete owner, authorization, claim, acknowledgement, replay, history, catch-up, one-shot, delivery, and client-compatibility contract before schedule-only occurrences can ship.
• Avoid wake for a contract that may not wake anything.

Implementation shape

The RFC defines independently reviewable slices for:

• projection lifecycle and contract tests;
• a bounded plugin SDK registrar interface;
• host-owned durable CAS arbitration;
• restart, cancellation, supersession, and already-due behavior;
• recovery and readiness generation composition;
• an optional later schedule-only occurrence protocol.

Validation

• RFC template structure and required sections checked.
• RFC number checked against current main and open RFC PRs.
• Markdown whitespace checked with git diff --check.
• Draft checked for the repository's punctuation and prose rules.
• Current OpenClaw cron domain, Gateway schema, SQLite codecs, scheduler reservation/finalization, projection hooks, CLI/tooling, Control UI, macOS, Android, heartbeat, recovery proposals, and related RFCs inspected.

Related work

• openclaw/openclaw#119040
• openclaw/openclaw#119035
• openclaw/openclaw#114145
• openclaw/openclaw#103647
• openclaw/openclaw#104368
• openclaw/rfcs#5
• openclaw/rfcs#46

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 4, 2026, 2:01 PM ET / 18:01 UTC.

ClawSweeper review

What this changes

Adds RFC 0029, proposing plugin-owned reconciled Automation deadline snapshots for hosts while deferring schedule-only occurrence completion until its lifecycle contract is designed.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep open. This is a current, coherent RFC draft proposing a new Automation-to-host contract; it is neither implemented on main nor safely reducible to an existing RFC without maintainer direction.

Priority: P2
Reviewed head: 7c4370b6dc36102371e4c618715c9f517fd40c4e
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The draft is coherent, but acceptance depends on maintainer alignment for a new public contract.
Proof confidence	🌊 off-meta tidepool	Not applicable: This documentation-only RFC does not require runtime behavior proof before design review.
Patch quality	🦐 gold shrimp (3/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This documentation-only RFC does not require runtime behavior proof before design review.
Evidence reviewed	4 items	Current main: Current main ends at RFC 0027, so this RFC 0029 proposal is not already present on the default branch. RFC lifecycle: Repository guidance requires new RFCs to remain drafts until acceptance and then receive an implementation issue before merging; the submitted metadata uses draft status and an empty issue field. Automation history: Omar Shahine authored the current-main Automations terminology RFC, providing direct recent history on this product surface.
Findings	None	None.
Security	None	None.

How this fits together

Automations schedule and execute work inside OpenClaw. This proposal exports a bounded deadline view to hosts that manage compute availability without transferring ownership of Automation execution or history.

flowchart LR
  A[Automation schedules] --> B[Scheduler reconciliation]
  B --> C[Plugin deadline snapshot]
  C --> D[Host activates compute]
  D --> E[OpenClaw executes automation]
  E --> F[Run history]

Loading

Decision needed

Question	Recommendation
Should OpenClaw accept a plugin-owned deadline-projection boundary now and explicitly defer externally completed schedule-only occurrences?	Accept the projection boundary: Adopt a narrow reconciled deadline registrar and require a focused implementation issue after RFC acceptance.

Why: The choice establishes a future public contract across Automations, plugins, and hosts; repository evidence cannot determine intended product direction.

Before merge

• Add real behavior proof - Not applicable: This documentation-only RFC does not require runtime behavior proof before design review.
• Resolve merge risk (P1) - The RFC needs to distinguish its registrar from the open scheduler-seam proposal to avoid parallel plugin contracts.
• Resolve merge risk (P1) - No schedule-only occurrence should ship until authorization, claim, acknowledgement, replay, and compatibility semantics are approved.
• Complete next step (P2) - A maintainer must select the intended Automation-to-host contract before implementation can safely be planned.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Proposal size	1 file added, 660 lines	The change defines a substantial cross-product contract that merits focused boundary review.

Merge-risk options

Maintainer options:

1. Resolve API ownership before merge (recommended)
   Obtain a maintainer decision on the relationship to the scheduler-seam proposal and make the phase-one compatibility and authorization boundary explicit.
2. Pause for roadmap sponsorship
   Keep the RFC draft unmerged if the project does not want to make this host-facing contract a supported direction now.

Technical review

Best possible solution:

Accept one clearly scoped host-facing Automation boundary: a read/projection registrar in phase one, with any externally completed occurrence treated as a separately approved future protocol.

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

Not applicable: this is a new design proposal, not a failure report.

Is this the best way to solve the issue?

Unclear: separating host activation from Automation completion is coherent, but maintainers must first settle the public boundary against the existing scheduler RFC.

AGENTS.md: not found in the target repository.

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

Labels

Label changes:

• add P2: This is a meaningful but non-urgent architecture proposal.
• add merge-risk: 🚨 compatibility: The proposed registrar would establish a compatibility surface for plugins, hosts, and clients.
• add merge-risk: 🚨 security-boundary: Host interaction around Automation work requires explicit authorization and acknowledgement semantics.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This documentation-only RFC does not require runtime behavior proof before design review.

Label justifications:

• P2: This is a meaningful but non-urgent architecture proposal.
• merge-risk: 🚨 compatibility: The proposed registrar would establish a compatibility surface for plugins, hosts, and clients.
• merge-risk: 🚨 security-boundary: Host interaction around Automation work requires explicit authorization and acknowledgement semantics.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This documentation-only RFC does not require runtime behavior proof before design review.

Evidence

What I checked:

• Current main: Current main ends at RFC 0027, so this RFC 0029 proposal is not already present on the default branch. (af708f0ddb6f)
• RFC lifecycle: Repository guidance requires new RFCs to remain drafts until acceptance and then receive an implementation issue before merging; the submitted metadata uses draft status and an empty issue field. (README.md:78, af708f0ddb6f)
• Automation history: Omar Shahine authored the current-main Automations terminology RFC, providing direct recent history on this product surface. (rfcs/0026-automations-terminology.md:1, c876de6210bf)
• Submitted scope: Provided PR metadata identifies one new 660-line RFC defining a deadline-projection boundary and explicitly deferring an external schedule-only completion protocol. (rfcs/0029-external-automation-deadlines.md:1, 7c4370b6dc36)

Likely related people:

• Omar Shahine: Authored current-main RFC 0026 on Automations and both commits in this proposed RFC. (role: recent Automation RFC contributor; confidence: high; commits: c876de6210bf, 508be4d0091b, 7c4370b6dc36; files: rfcs/0026-automations-terminology.md, rfcs/0029-external-automation-deadlines.md)
• amittell: The supplied related-item context identifies their open scheduler-seam RFC as overlapping work on a plugin scheduling boundary. (role: adjacent scheduler proposal author; confidence: low; commits: d17aeeac9ef3)

Rank-up moves

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

• Resolve the relationship to the scheduler-seam RFC and confirm the phase-one contract boundary.

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.