Summary

What problem does this PR solve?

Scheduled shell-style cron work currently has to go through an isolated agent/model run, which adds setup pressure and makes simple command jobs more expensive and more fragile than they need to be.

Why does this matter now?

Gateway cron pressure is visible in production-style scheduled workloads. Staggering existing schedules is still the right immediate load-reduction step, but OpenClaw also needs a first-class path for jobs that are command execution rather than agent reasoning.

What is the intended outcome?

Command cron jobs can be stored, edited, and executed by the gateway scheduler as command payloads, with stdout/stderr capture, timeout handling, output limits, failure reporting, and NO_REPLY suppression. openclaw doctor --fix can convert exact legacy command-template agent jobs only when they already had shell-capable tool access, and it warns on mixed shell-style agent prompts that still need manual conversion.

What is intentionally out of scope?

Command authoring remains CLI-first in this PR. The UI preserves and displays existing command cron jobs, but it does not add a full command-job authoring flow. This PR also does not rewrite arbitrary natural-language agent cron prompts into commands.

What does success look like?

Existing agent cron jobs keep working, command cron payloads round-trip through schema/store/CLI/UI surfaces, the gateway cron runner executes command jobs without starting an isolated agent/model run, and doctor does not silently turn restricted agent prompts into gateway shell execution.

What should reviewers focus on?

Cron payload compatibility, command execution boundaries, output suppression semantics, timeout/error behavior, doctor migration safety, and whether the CLI/API surface is narrow enough for this first step.

Linked context

Which issue does this close?

No closing issue yet. Candidate canonical tracker is #18160, but this PR leaves it as related until maintainers decide whether CLI/API-first command jobs are enough to close the broader direct-exec cron request.

Which issues, PRs, or discussions are related?

Related #18160, #62789, #64598, #69455, #61152, #63107, #82662, #84567, #86893, #89055, #89442.

Was this requested by a maintainer or owner?

Owner/maintainer requested in response to production cron pressure and the need to run shell-style scheduled work inside OpenClaw instead of as separate OS cron jobs.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: Scheduled command jobs can be stored and executed as command payloads by the gateway cron runner, including stdout/stderr capture, timeout handling, output limits, and NO_REPLY suppression. Doctor also distinguishes safe exact command-template conversion from unresolved shell-style agent prompts.
• Real environment tested: Local OpenClaw source checkout on macOS; representative command cron jobs on a deployed maintainer gateway.
• Exact steps or command run after this patch: git diff --check origin/main...HEAD; node scripts/run-vitest.mjs src/commands/doctor/cron/store-migration.test.ts src/commands/doctor/cron/index.test.ts src/cron/command-runner.test.ts src/cron/normalize.test.ts; AUTOREVIEW_AUTO_TESTS=0 .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main --prompt 'Only report P0/P1 correctness, data-loss, security, or production-breakage findings. Omit P2/P3 findings entirely. Focus on command cron execution boundaries, doctor migration false positives/false negatives, delivery semantics, and whether unresolved shell-style agentTurn jobs are handled safely.'; deployed gateway openclaw cron run --wait on representative command cron jobs that cover silent NO_REPLY, announced media output, and delivery suppression.
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Focused Vitest shards passed: unit-fast 23 tests, cron 56 tests, commands 25 tests. git diff --check origin/main...HEAD passed. P0/P1-scoped autoreview reported autoreview clean: no accepted/actionable findings reported. Deployed command cron runs returned status: ok for silent NO_REPLY jobs and for an announced media-output job; the announced run delivered successfully, while silent runs were not delivered.
• Observed result after fix: Command cron payloads validate, persist, normalize, execute, report output, suppress silent output, and round-trip through the tested CLI/store/UI surfaces. Doctor converts exact legacy command templates only when the legacy job already had shell-capable tool access; restricted command-shaped prompts and mixed shell-style agent prompts are left as agent jobs and reported for manual conversion.
• What was not tested: Full CI has not completed on this refreshed head. The deployed gateway proof used existing representative command jobs rather than a newly created public demo job.
• Proof limitations or environment constraints: Live proof is redacted to avoid publishing private gateway identifiers, job names, chat targets, or workflow details. Local tests cover the doctor migration safety cases added after the live incident.
• Before evidence (optional but encouraged): Existing scheduled shell-style work had no first-class cron command payload path and had to be represented as agent/model work or moved outside OpenClaw.

Tests and validation

Which commands did you run?

git diff --check origin/main...HEAD

node scripts/run-vitest.mjs src/commands/doctor/cron/store-migration.test.ts src/commands/doctor/cron/index.test.ts src/cron/command-runner.test.ts src/cron/normalize.test.ts

AUTOREVIEW_AUTO_TESTS=0 .agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main --prompt 'Only report P0/P1 correctness, data-loss, security, or production-breakage findings. Omit P2/P3 findings entirely. Focus on command cron execution boundaries, doctor migration false positives/false negatives, delivery semantics, and whether unresolved shell-style agentTurn jobs are handled safely.'

Deployed gateway openclaw cron run --wait on representative command cron jobs covering silent output, media output, and delivery suppression.

What regression coverage was added or updated?

Protocol cron validators, cron store/normalization, command runner, gateway cron execution, CLI cron add/edit behavior, agent cron tool rejection of command payloads, UI cron controller preservation/display coverage, and doctor migration coverage for exact command-template conversion versus unresolved shell-style agent prompts. Follow-up coverage pins command timeout/no-output/abort failures as cron errors, keeps delivery-only / timeout-only CLI edits from corrupting existing command payloads, prevents restricted agent prompts from being auto-converted into gateway shell commands, and warns on omitted/wildcard shell-capable tool allowlists.

What failed before this fix, if known?

Command cron payloads were not a supported first-class scheduled job type, so the gateway cron runner could not execute shell-style work directly as a cron command payload. Legacy shell-style agent prompts could also remain model-mediated and fail in isolated cron sessions without shell/process tools.

If no test was added, why not?

N/A. Focused regression coverage was added/updated across the touched surfaces.

Risk checklist

Did user-visible behavior change? (Yes/No)

Yes. CLI/API cron jobs can now include command payloads, existing command jobs are preserved/displayed by the UI, and doctor can repair or flag legacy shell-style cron payloads.

Did config, environment, or migration behavior change? (Yes/No)

Yes. openclaw doctor --fix now performs bounded command-cron payload repair for exact legacy templates and reports unresolved shell-style agent prompts that require manual conversion.

Did security, auth, secrets, network, or tool execution behavior change? (Yes/No)

Yes. This adds a first-class scheduled command execution path inside the gateway cron runner.

What is the highest-risk area?

Command execution semantics and migration safety: command jobs must be explicit command payloads, bounded by timeout/output limits, and doctor must not silently escalate restricted agent prompts into gateway shell execution.

How is that risk mitigated?

The implementation keeps command authoring CLI/API scoped, rejects command payloads from the agent cron tool, runs commands through bounded command-runner coverage, caps output, records stderr/stdout, reports failures, preserves NO_REPLY suppression behavior, converts only exact command-template legacy jobs with shell-capable tool access, and warns rather than auto-converting ambiguous shell-style agent prompts.

Current review state

What is the next action?

Maintainer review and GitHub CI. The PR remains draft because this touches command execution and migration behavior and should get explicit maintainer review before being marked ready.

What is still waiting on author, maintainer, CI, or external proof?

Waiting on CI for the refreshed head and maintainer judgment on the command execution boundary. No known P0/P1 autoreview findings remain.

Which bot or reviewer comments were addressed?

P0/P1-scoped autoreview initially found two doctor migration safety issues: restricted command-shaped prompts could be auto-converted, and omitted/wildcard tool allowlists were not reported as shell-capable. Both were fixed with regression tests, and the final P0/P1-scoped autoreview run was clean.