RFC 0018: Readiness Conditions and Providers

[giodl73-repo]

Decision Requested

Should OpenClaw add an opt-in, structured, subject-aware readiness contract around its existing Gateway checker?

This RFC covers Readiness Conditions and Providers. Standard Hosting Profiles remain a separate product/support decision in RFC 0023.

Why

OpenClaw already exposes /ready and /readyz, but their evaluator is purpose-built around fixed Gateway observations. Operators cannot select which known runtime facts their deployment requires, plugins cannot contribute bounded observations, and a single result cannot identify the different runtime subjects those observations describe.

Proposed V1

Each condition has stable type, subjectRef, status, requirement, reason, and message fields, with optional bounded related subjects. Required False or Unknown conditions fail readiness; advisory conditions remain visible. Activated /ready, /readyz, Gateway health/status projections, and openclaw ready consume the same canonical result. HTTP /health and /healthz remain shallow liveness.

Health/status consumers can derive one selected-condition state without changing or re-evaluating conditions:

• required False -> failing
• required Unknown without a required failure -> unknown
• advisory non-True with all required conditions true -> degraded
• every selected condition true -> passing

Detailed local or authenticated status reuses each condition's stable reason, bounded redacted message, and subject references. Unauthenticated remote output exposes only the aggregate status and readiness boolean. A separate /statusz may expose this diagnostic projection while /healthz remains liveness and /readyz remains traffic admission.

The result declares its producer and a versioned reconciled subject package once. IDs renew at the lifecycle boundary owned by each subject: optional host workload, process, Gateway serving lifecycle, config, plugin, node, or another resource. A generation revises the same object. Operators can therefore diff (subjectRef, type) and distinguish a condition transition from replacement or revision.

OpenClaw retains no history. Hosts and telemetry systems may store and diff the bounded result. This gives Docker, Kubernetes, OCC, and other operators enough attribution to explain a readiness transition without turning readiness into a resource store or control plane.

Operators select reusable criteria through gateway.readiness. Registering a criterion never selects it. Plugin providers are namespaced, enumerable, observational, advisory by default, and receive a subject collector. Core owns deadlines, cancellation, coalescing, caching, output bounds, redaction, reconciliation, deterministic ordering, and fail-closed projection.

This PR includes the normative Readiness v1 and Readiness Subjects v1 sidecars. Its non-normative platform comparison maps the design to Kubernetes, Docker, systemd, ASP.NET Core, Spring Boot, and OpenTelemetry.

Proposed Condition Catalog

Area	Conditions	How they participate
Gateway serving baseline	GatewayStartupComplete, GatewayAcceptingWork, ChannelRuntimeReady, ConfigLoaded	Universal required conditions that modernize existing Gateway observations.
Gateway diagnostics	ChannelRuntimeSuppressed, EventLoopHealthy, PluginsLoaded	Visible advisories; the selectable conditions may be promoted to required.
Runtime activation	WorkspaceWritable, ConfigCurrent, ModelRouteReady, SecretsReady	Selectable checks for the active workspace, config, model/auth route, and secret owners.
Agent execution	ContextEngineReady, ToolCatalogReady, McpRuntimeReady, SandboxReady, HarnessReady	Selectable observations from the OpenClaw owners of each execution capability.
State and background services	SessionStorageReady, StateReady, DeliveryRuntimeReady, SchedulerReady	Selectable storage, state, delivery, and scheduler lifecycle observations.
Plugin dependencies	plugin.<plugin-id>.<criterion-id>	Activated plugins may register bounded, namespaced observations; they remain advisory unless selected as required.

ReadinessEvaluationComplete and remote GatewayResponding guard failures keep incomplete evaluation or an unreachable Gateway explicit. Merely implementing or registering a condition never selects it. Outside the universal baseline, only gateway.readiness configuration or a separately accepted Hosting Profile changes what must pass.

Compatibility Boundary

• Without gateway.readiness or another accepted activation contract, /ready and /readyz use the legacy checker.
• Presence of gateway.readiness, including {}, activates bounded canonical evaluation.
• Selected but unobserved facts remain explicit Unknown conditions.
• A separately accepted Standard Hosting Profile may activate the same evaluator by selecting a named condition set.
• Selected-condition health is a projection outside CanonicalReadinessResult; it does not change readiness contract version 1.
• /health and /healthz remain shallow liveness. /statusz is diagnostic and returns 200 after successful evaluation regardless of condition-health state.

Implementation Stack

1. PR 104018 adds the readiness framework, providers, canonical projections, CLI, and subject identity at exact head abbdfa0876f.
2. PR 113421 adds reusable OpenClaw-owned conditions for core runtime owners at exact head a7e0df75ff2. It depends on PR 104018.
3. PR 121355 derives condition health for Gateway health/status and adds /statusz at exact head 8cb054a8f47. It is stacked after PR 114636 to avoid reopening the rebased implementation/profile stack, but it has no runtime dependency on Hosting Profiles.

The framework and owner PRs are profile-free and independently adoptable. Owner criteria observe existing snapshots. Readiness does not make model calls, acquire credentials, connect MCP servers, start sandboxes or harnesses, open databases, or start schedulers. Active filesystem checks and provider calls are bounded.

Operator Facilities

• Validated follow-up work demonstrates openclaw ready --watch with bounded semantic transitions, recovery, and subject-lifetime replacement without changing one-shot behavior.
• Validated follow-up work demonstrates an inert readiness catalog and openclaw ready criteria list|inspect without invoking providers.
• Validated follow-up work demonstrates openclaw ready --wait [duration] as a bounded startup gate over the canonical ready RPC.
• Validated follow-up work demonstrates human explanations for the identity, generation, parent, and lifetime of subjects behind non-passing conditions.
• Doctor, telemetry, support bundles, and updates consume readiness evidence through their existing owners.

Package Proof

Exact-head package-installed Docker proof passes over the profile and release-artifact stack. It exercises RFC 0018 readiness surfaces, stable repeated polls, fail-closed transitions, and host-stable/process-and-Gateway-renewing container restart semantics using an immutable no-push package/image artifact.

Maintainer Questions

1. Is explicit activation the right upgrade boundary?
2. Is required/advisory the right modernization of the existing evaluator?
3. Is the producer/subject identity package the right attribution model?
4. Is activation-scoped plugin registration the right extension boundary?
5. Is a derived selected-condition health state plus separate /statusz the right diagnostic projection while /healthz remains shallow?

[clawsweeper]

Codex review: blocked before merge. Reviewed September 9, 2026, 1:20 AM ET / 05:20 UTC (Revision 145).

ClawSweeper review

What this changes

Adds an RFC and three supporting documents defining opt-in Gateway readiness conditions, plugin observations, runtime subject identity, and shared diagnostic output.

Merge readiness

⛔ Blocked before merge - 4 items remain

The two prior specification findings are resolved. This remains a distinct, useful proposal absent from the default branch; acceptance of the readiness contract still requires the repository’s maintainer discussion and RFC approval process.

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

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A coherent, supported RFC with the two prior specification defects fixed; the remaining acceptance decision does not reduce patch quality.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (linked_artifact): Existing package-installed Docker evidence supports the proposed Gateway readiness path through HTTP and CLI failure/recovery transitions and identity renewal. Its previously sufficient classification is preserved; the new text clarifies the recovery contract, while complete runtime conformance belongs to implementation review. Hosted logs could not be independently reopened in this environment.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (linked_artifact): Existing package-installed Docker evidence supports the proposed Gateway readiness path through HTTP and CLI failure/recovery transitions and identity renewal. Its previously sufficient classification is preserved; the new text clarifies the recovery contract, while complete runtime conformance belongs to implementation review. Hosted logs could not be independently reopened in this environment.
Evidence reviewed	9 items	Verified proposal scope and default branch: The pinned default-branch comparison adds exactly four Markdown documents and 1,836 lines. The default-branch tree contains no readiness RFC or normative readiness sidecars; this PR changes no executable implementation. Both prior findings resolved: The head commit replaces the undefined result-type reference with ReadinessResult and explicitly specifies quarantine across reload, recovery after Gateway process restart, and a conformance case preserving one outstanding callback per process. RFC acceptance contract: README requires a maintainer-discussion thread, acceptance, an implementation issue, and accepted frontmatter before merging. This proposal remains status: draft with its issue field blank; the supplied discussion does not establish acceptance.
Findings	None	None.
Security	None	None.

How this fits together

Gateway readiness tells operators whether OpenClaw can accept work. The proposed evaluator combines selected runtime and plugin observations into one result for readiness probes, health/status output, and CLI consumers.

flowchart TD
  A[Operator selection] --> B[Readiness evaluator]
  C[Core runtime observations] --> B
  D[Activated plugin observations] --> B
  B --> E[Bounded conditions and subject identity]
  E --> F[Required conditions pass]
  F --> G[Readiness probe response]
  E --> H[Health status and CLI diagnostics]

Loading

Decision needed

Question	Recommendation
Should OpenClaw accept this opt-in readiness and plugin-provider contract, including process-restart recovery for permanently quarantined callbacks, independently of hosting profiles?	Accept readiness independently: Record acceptance through the required discussion, link an implementation issue, and update the RFC metadata while leaving hosting profiles to their separate decision.

Why: The specification issues are resolved, but choosing a permanent plugin/configuration contract and accepting the RFC requires maintainer intent under README’s lifecycle.

Before merge

• Resolve merge risk (P1) - Accepting the RFC establishes a new plugin registration and configuration contract. Maintainers must endorse explicit activation and the documented process-restart recovery requirement for permanently pending required providers; this Markdown PR itself changes no running installation.
• Resolve merge risk (P1) - The review environment could inspect the linked proof run and successful steps but could not reopen its hosted logs. Published-upgrade and implementation conformance remain separate runtime-PR obligations.
• Complete next step (P2) - Record the required maintainer discussion and acceptance decision; if accepted, link the implementation issue and change RFC status from draft to accepted before merge.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Change surface	4 Markdown files, +1,836 lines; production +0, tests +0	Review concerns are specification consistency and product acceptance; executable implementation lives in separate PRs.

Merge-risk options

Maintainer options:

1. Approve the explicit activation contract (recommended)
   Accept the proposed plugin API and recovery semantics through the RFC process, retaining implementation-level upgrade validation before runtime changes land.
2. Keep API scope in draft
   Pause acceptance until maintainers choose a narrower permanent registration and selection contract.

Technical review

Best possible solution:

Accept a bounded, explicitly activated readiness contract independently of hosting profiles, preserving legacy probes and assigning upgrade and recovery conformance to the implementation PRs.

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

Not applicable: this is a design proposal, and both previously reported specification defects are resolved in the current text.

Is this the best way to solve the issue?

Yes, the opt-in evaluator and shared projections form a coherent design that preserves existing defaults; final API and product acceptance remain maintainer choices.

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P2: This is a substantive operational-readiness proposal with concrete design and implementation evidence, without an urgent runtime regression in this patch.
• merge-risk: 🚨 compatibility: RFC acceptance would establish a new plugin API and activation contract whose permanent compatibility semantics require maintainer approval.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. One bounded, subject-aware readiness result could replace fragmented host checks while explaining failures consistently across probes and operator tools.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (linked_artifact): Existing package-installed Docker evidence supports the proposed Gateway readiness path through HTTP and CLI failure/recovery transitions and identity renewal. Its previously sufficient classification is preserved; the new text clarifies the recovery contract, while complete runtime conformance belongs to implementation review. Hosted logs could not be independently reopened in this environment.
• proof: sufficient: Contributor real behavior proof is sufficient. Existing package-installed Docker evidence supports the proposed Gateway readiness path through HTTP and CLI failure/recovery transitions and identity renewal. Its previously sufficient classification is preserved; the new text clarifies the recovery contract, while complete runtime conformance belongs to implementation review. Hosted logs could not be independently reopened in this environment.

Evidence

What I checked:

• Verified proposal scope and default branch: The pinned default-branch comparison adds exactly four Markdown documents and 1,836 lines. The default-branch tree contains no readiness RFC or normative readiness sidecars; this PR changes no executable implementation. (rfcs/0018-readiness-conditions-and-providers.md:15, b09eed5edeac)
• Both prior findings resolved: The head commit replaces the undefined result-type reference with ReadinessResult and explicitly specifies quarantine across reload, recovery after Gateway process restart, and a conformance case preserving one outstanding callback per process. (rfcs/0018/readiness-v1-spec.md:450, b09eed5edeac)
• RFC acceptance contract: README requires a maintainer-discussion thread, acceptance, an implementation issue, and accepted frontmatter before merging. This proposal remains status: draft with its issue field blank; the supplied discussion does not establish acceptance. (README.md:78, b09eed5edeac)
• Compatibility and security boundaries: The specification preserves legacy evaluation without activation, keeps unselected providers inert, prohibits callbacks in configuration, constrains plugin namespaces, and limits unauthenticated output. Subject identities explicitly confer no security authority. (rfcs/0018/readiness-v1-spec.md:53, b09eed5edeac)
• Existing health work is distinct: The accepted Doctor proposal governs ordered diagnostic and repair contributions, not Gateway traffic admission. The open hosting-profile proposal explicitly composes this readiness contract and does not replace it: RFC 0023: Standard Hosting Profiles #37. (rfcs/needs_refactoring/doctor-health-upgrades.md:41, b09eed5edeac)
• Implementation remains a separate open PR: The RFC explicitly identifies the OpenClaw runtime implementation as feat: add readiness conditions and providers openclaw#104018. GitHub confirms it remains open and unmerged at the stated framework head; it does not establish implementation or acceptance on this repository’s default branch. (abbdfa0876fe)

Likely related people:

• kevinslin: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• giodl73-repo: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

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 (144 earlier review cycles; latest 8 shown)

• reviewed 2026-08-30T12:35:26.750Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Use the declared canonical result type | [P2] Link the required maintainer discussion | [P3] Remove the trailing whitespace
• reviewed 2026-09-01T13:02:34.692Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Use the declared canonical result type | [P2] Link the required maintainer discussion | [P3] Remove the trailing whitespace
• reviewed 2026-09-01T20:51:05.904Z sha 247d952 :: needs real behavior proof before merge. :: [P1] Define recovery after a provider ignores cancellation | [P2] Use the declared canonical result type | [P2] Link the required maintainer discussion | [P3] Remove the trailing whitespace
• reviewed 2026-09-03T06:04:05.301Z sha 247d952 :: needs real behavior proof before merge. :: [P1] Permit recovery after a provider ignores cancellation | [P2] Name the declared canonical result type | [P2] Create and link the required maintainer discussion | [P3] Remove trailing whitespace
• reviewed 2026-09-03T12:40:05.262Z sha 247d952 :: needs real behavior proof before merge. :: [P1] Permit recovery from permanently pending providers | [P2] Use the declared canonical result type | [P2] Link the required maintainer discussion
• reviewed 2026-09-03T19:38:07.641Z sha 247d952 :: needs real behavior proof before merge. :: [P1] Permit recovery from permanently pending providers | [P2] Use the declared canonical result type | [P2] Link the required maintainer discussion
• reviewed 2026-09-04T14:53:50.613Z sha 247d952 :: needs real behavior proof before merge. :: [P1] Permit recovery from permanently pending providers | [P2] Use the declared canonical result type | [P2] Link the required maintainer discussion | [P3] Remove the trailing whitespace
• reviewed 2026-09-05T18:59:20.489Z sha 247d952 :: blocked before merge. :: [P2] Specify recovery from permanent provider quarantine | [P3] Use the declared readiness result name

[giodl73-repo]

Refreshed onto current main at b09eed5 and resolved the two current specification findings. Permanent provider quarantine now has one bounded recovery boundary: it persists across config/plugin reload and clears only when the callback settles or the Gateway process restarts after operator repair, with an explicit conformance case. The health projection now refers to the declared ReadinessResult type. git diff --check passes. @clawsweeper re-review