Greptile Summary

This PR adds payload.kind="command" support to cron add and cron edit CLI commands, wires up the runCommandJob dep in the gateway's cron service, and extends the gateway protocol schema and normalization layer to handle the new payload type.

Two P1 defects were found in the new edit path that need to be addressed before merging.

Confidence Score: 3/5

Not safe to merge as-is: two P1 defects in the edit path will cause silent data loss (--clear-args no-op) and runtime errors (delivery-flag-only edit corrupts payload kind).

The add path and server-side execution are solid, but the edit path has two deterministic correctness defects introduced by this PR: --clear-args is broken end-to-end across schema/normalize/merge layers, and editing delivery settings on an existing command job via CLI flags that feed hasAgentTurnPatch will cause the server to reject the patch.

src/cli/cron-cli/register.cron-edit.ts (delivery-flag / hasAgentTurnPatch logic), src/gateway/protocol/schema/cron.ts + src/cron/normalize.ts + src/cron/service/jobs.ts (clear-args null propagation chain)

This is a comment left during a code review.
Path: src/cli/cron-cli/register.cron-edit.ts
Line: 200-246

Comment:
**Delivery-flag-only edit corrupts command payload kind**

When a user edits delivery settings on an existing command payload job using `--announce` (or `--channel`, `--to`, `--account`, `--best-effort-deliver`) without any `--command` flag, `hasDeliveryModeFlag` is `true`, which forces `hasAgentTurnPatch = true`. The `else if (hasAgentTurnPatch)` branch then sets `patch.payload = { kind: "agentTurn" }` (no message). On the server, `mergeCronPayload` sees a kind mismatch and calls `buildPayloadFromPatch`, which throws `'cron.update payload.kind="agentTurn" requires message'`. The edit fails and the delivery config is never updated.

Delivery flags should not be included in the `hasAgentTurnPatch` condition used to set the payload kind. The delivery update (line 273) already runs independently of the payload block; the payload block should only trigger when a payload-specific flag is present.

```
const hasAgentTurnPatch =
  typeof opts.message === "string" ||
  Boolean(model) ||
  Boolean(thinking) ||
  typeof opts.lightContext === "boolean" ||
  typeof opts.tools === "string" ||
  opts.clearTools;
```

The delivery fields (`hasDeliveryModeFlag`, `hasDeliveryTarget`, `hasDeliveryAccount`, `hasBestEffort`) can stay in the delivery block at line 273 without being part of the payload-kind discriminator.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/gateway/protocol/schema/cron.ts
Line: 172-175

Comment:
**`--clear-args` is silently a no-op for command payload patch**

The CLI sends `payload.args = null` when `--clear-args` is passed. Three layers prevent this from working:

1. **Protocol schema** (here): `args` in `CronPayloadPatchSchema` is typed as `Type.Array(Type.String())` — `null` is not accepted, unlike `toolsAllow` in the agentTurn variant which explicitly uses `Type.Union([Type.Array(Type.String()), Type.Null()])`.
2. **Normalize layer** (`src/cron/normalize.ts:223-230`): `normalizeTrimmedStringArray(next.args)` is called without `{ allowNull: true }`, so `null` normalises to `undefined` and the key is deleted from the patch.
3. **Merge layer** (`src/cron/service/jobs.ts:672`): `if (Array.isArray(patch.args))` never fires for `null`, so existing args are silently preserved.

The fix needs to mirror the `toolsAllow` pattern used for agentTurn:

```suggestion
  cronCommandPayloadSchema({
    command: Type.Optional(NonEmptyString),
    args: Type.Optional(Type.Union([Type.Array(Type.String()), Type.Null()])),
  }),
```

Additionally, `src/cron/normalize.ts` should call `normalizeTrimmedStringArray(next.args, { allowNull: true })`, and `mergeCronPayload` in `src/cron/service/jobs.ts` should add `else if (patch.args === null) { delete next.args; }` after the `Array.isArray` check.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/cli/cron-cli/register.cron-add.ts
Line: 226-239

Comment:
**Error messages still say "agentTurn" after command payload support was added**

Both error messages mention `agentTurn` as the required payload kind, but the checks now apply equally to command payload jobs (any non-systemEvent isolated job). A user passing `--announce` with `--command` on a main session, or passing `--account` with a command job, will see a confusing error.

```suggestion
            throw new Error(
              "--announce/--no-deliver require an isolated/current/session non-systemEvent job.",
            );
```

And for line 238:
```
throw new Error("--account requires a non-main, non-systemEvent job with delivery.");
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "cron: add command payload cli support" | Re-trigger Greptile}

Split update: I force-pushed this branch to the backend/runtime/server scope only, and opened the stacked CLI follow-up here: rocdesu#1\n\nThat should make the review boundary match the PR description again.

Push update:

• removed unrelated diff drift so this branch is now cron/gateway-only
• current PR scope remains backend/runtime/server only; CLI follow-up lives in rocdesu/openclaw#1
• locally verified:
  • node scripts/run-vitest.mjs run --config test/vitest/vitest.gateway.config.ts src/gateway/server.cron.test.ts src/gateway/protocol/cron-validators.test.ts
  • node scripts/test-projects.mjs src/cron/normalize.test.ts src/cron/run-log.test.ts

For reviewer context: earlier automated comments about cron add / cron edit CLI issues were against the pre-split branch state, not the current backend-only diff.

Reviewer nudge: this branch has been force-pushed and re-scoped to backend/runtime/server only for cron command payload execution.

The CLI follow-up is split out to rocdesu#1, so earlier automated comments about cron add / cron edit CLI issues are stale relative to the current diff.

Locally re-verified on the current branch:

• node scripts/run-vitest.mjs run --config test/vitest/vitest.gateway.config.ts src/gateway/server.cron.test.ts src/gateway/protocol/cron-validators.test.ts
• node scripts/test-projects.mjs src/cron/normalize.test.ts src/cron/run-log.test.ts

Would appreciate a fresh review on the current narrowed scope.

@steipete @brunolorente @openclaw/secops quick nudge for a fresh look on the current narrowed diff when convenient. 🙏

Thanks for the idea. I checked the current extension path, and this is a better fit for the ClawHub/community tide pool than OpenClaw core.

This PR adds a first-class core cron payload.kind="command" execution path, but current main still intentionally limits cron payloads to systemEvent and agentTurn. The requested deterministic command scheduling can be built outside core with the existing native plugin surface: plugins can register Gateway lifecycle hooks and CLI/command surfaces, observe/manage cron jobs, short-circuit cron-triggered agent turns before model execution via before_agent_reply, and run local commands through the public process runtime helper. The PR also expands a security-sensitive Gateway command-execution path and had substantial review feedback around delivery, timeout, and process-lifecycle correctness, so the conservative cleanup path is to move this capability to a ClawHub/plugin implementation rather than merge a new core payload kind.

Best possible solution:

Close this core PR and move the feature to a ClawHub/native plugin: store plugin-owned command job config, use existing cron scheduling or a plugin-owned Gateway service, short-circuit cron-triggered agent turns before model execution with before_agent_reply, execute via runCommandWithTimeout, and only propose a new plugin API if that implementation hits a concrete missing seam.

What I checked:

• Current cron payload contract excludes command payloads: CronPayload and CronPayloadPatch are only systemEvent or agentTurn on current main; there is no command payload variant to preserve or close as implemented. (src/cron/types.ts:114, e476523082a6)
• Current cron validation rejects command-style isolated payloads: Current main requires isolated/current/session cron jobs to use payload.kind="agentTurn", so the PR's core behavior is not already present. (src/cron/service/jobs.ts:172, e476523082a6)
• Current execution path remains agent-turn only: The isolated cron executor returns skipped for any payload kind other than agentTurn, confirming command jobs are not implemented on main. (src/cron/service/timer.ts:1366, e476523082a6)
• Gateway wire schema excludes command payloads: The cron protocol schema only accepts systemEvent and agentTurn payloads in current main; adding command would be a new core protocol surface, not cleanup of an existing one. (src/gateway/protocol/schema/cron.ts:133, e476523082a6)
• Product direction favors plugins for optional capabilities: VISION.md says core should stay lean, optional capability should usually ship as plugins, and plugin promotion/discovery belongs in ClawHub. (VISION.md:54, e476523082a6)
• Existing plugin APIs can host the capability: Plugin docs expose native plugins, runtime side effects, lifecycle hooks, CLI/command registration, before_agent_reply short-circuiting, cron lifecycle observation, and Gateway cron access; the runtime surface also exposes runCommandWithTimeout for command execution without adding a new core payload kind. Public docs: docs/plugins/hooks.md. (docs/plugins/hooks.md:81, e476523082a6)

So I’m closing this as a scope-fit item for the plugin/community path rather than keeping it open as an OpenClaw core request.

Codex review notes: model gpt-5.5, reasoning high; reviewed against e476523082a6.