fengming 0.3.10 → 0.3.12

package/docs/automation/cron-jobs.md

@@ -1,534 +0,0 @@
----
-summary: "Scheduled jobs, webhooks, and Gmail PubSub triggers for the Gateway scheduler"
-read_when:
-  - Scheduling background jobs or wakeups
-  - Wiring external triggers (webhooks, Gmail) into FengMing
-  - Deciding between heartbeat and cron for scheduled tasks
-title: "Scheduled tasks"
-sidebarTitle: "Scheduled tasks"
----
-
-Cron is the Gateway's built-in scheduler. It persists jobs, wakes the agent at the right time, and can deliver output back to a chat channel or webhook endpoint.
-
-## Quick start
-
-<Steps>
-  <Step title="Add a one-shot reminder">
-    ```bash
-    fengming cron create "2026-02-01T16:00:00Z" \
-      --name "Reminder" \
-      --session main \
-      --system-event "Reminder: check the cron docs draft" \
-      --wake now \
-      --delete-after-run
-    ```
-  </Step>
-  <Step title="Check your jobs">
-    ```bash
-    fengming cron list
-    fengming cron get <job-id>
-    fengming cron show <job-id>
-    ```
-  </Step>
-  <Step title="See run history">
-    ```bash
-    fengming cron runs --id <job-id>
-    ```
-  </Step>
-</Steps>
-
-## How cron works
-
-- Cron runs **inside the Gateway** process (not inside the model).
-- Job definitions persist at `~/.fengming/cron/jobs.json` so restarts do not lose schedules.
-- Runtime execution state persists next to it in `~/.fengming/cron/jobs-state.json`. If you track cron definitions in git, track `jobs.json` and gitignore `jobs-state.json`.
-- If `jobs.json` contains malformed rows, the Gateway keeps valid jobs running, removes the malformed rows from the active store, and saves the raw rows beside it in `jobs-quarantine.json` for later repair or review.
-- After the split, older FengMing versions can read `jobs.json` but may treat jobs as fresh because runtime fields now live in `jobs-state.json`.
-- When `jobs.json` is edited while the Gateway is running or stopped, FengMing compares the changed schedule fields with pending runtime slot metadata and clears stale `nextRunAtMs` values. Pure formatting or key-order-only rewrites preserve the pending slot.
-- All cron executions create [background task](/automation/tasks) records.
-- On Gateway startup, overdue isolated agent-turn jobs are rescheduled out of the channel-connect window instead of replaying immediately, so Discord/Telegram startup and native-command setup stay responsive after restarts.
-- One-shot jobs (`--at`) auto-delete after success by default.
-- Isolated cron runs best-effort close tracked browser tabs/processes for their `cron:<jobId>` session when the run completes, so detached browser automation does not leave orphaned processes behind.
-- Isolated cron runs that receive the narrow cron self-cleanup grant can still read scheduler status, a self-filtered list of their current job, and that job's run history, so status/heartbeat checks can inspect their own schedule without gaining broader cron mutation access.
-- Isolated cron runs also guard against stale acknowledgement replies. If the first result is just an interim status update (`on it`, `pulling everything together`, and similar hints) and no descendant subagent run is still responsible for the final answer, FengMing re-prompts once for the actual result before delivery.
-- Isolated cron runs use structured execution-denial metadata from the embedded run, including node-host `UNAVAILABLE` wrappers whose nested error message starts with `SYSTEM_RUN_DENIED` or `INVALID_REQUEST`, so a blocked command is not reported as a green run while ordinary assistant prose is not treated as a denial.
-- Isolated cron runs also treat run-level agent failures as job errors even when no reply payload is produced, so model/provider failures increment error counters and trigger failure notifications instead of clearing the job as successful.
-- When an isolated agent-turn job reaches `timeoutSeconds`, cron aborts the underlying agent run and gives it a short cleanup window. If the run does not drain, Gateway-owned cleanup force-clears that run's session ownership before cron records the timeout, so queued chat work is not left behind a stale processing session.
-- If an isolated agent-turn stalls before the runner starts or before the first model call, cron records a phase-specific timeout such as `setup timed out before runner start` or `stalled before first model call (last phase: context-engine)`. These watchdogs cover embedded providers and CLI-backed providers before their external CLI process is actually started, and are capped independently from long `timeoutSeconds` values so cold-start/auth/context failures surface quickly instead of waiting for the full job budget.
-- If you use system cron or another external scheduler to run `fengming agent`, wrap it with a hard-kill escalation even though the CLI handles `SIGTERM`/`SIGINT`. Gateway-backed runs ask the Gateway to abort accepted runs; local and embedded fallback runs receive the same abort signal. For GNU `timeout`, prefer `timeout -k 60 600 fengming agent ...` over plain `timeout 600 ...`; the `-k` value is the supervisor backstop if the process cannot drain. For systemd units, keep the same shape by using a `SIGTERM` stop signal plus a grace window such as `TimeoutStopSec` before any final kill. If a retry reuses a `--run-id` while the original Gateway run is still active, the duplicate is reported as in-flight instead of starting a second run.
-
-<a id="maintenance"></a>
-
-<Note>
-Task reconciliation for cron is runtime-owned first, durable-history-backed second: an active cron task stays live while the cron runtime still tracks that job as running, even if an old child session row still exists. Once the runtime stops owning the job and the 5-minute grace window expires, maintenance checks persisted run logs and job state for the matching `cron:<jobId>:<startedAt>` run. If that durable history shows a terminal result, the task ledger is finalized from it; otherwise Gateway-owned maintenance can mark the task `lost`. Offline CLI audit can recover from durable history, but it does not treat its own empty in-process active-job set as proof that a Gateway-owned cron run is gone.
-</Note>
-
-## Schedule types
-
-| Kind    | CLI flag  | Description                                             |
-| ------- | --------- | ------------------------------------------------------- |
-| `at`    | `--at`    | One-shot timestamp (ISO 8601 or relative like `20m`)    |
-| `every` | `--every` | Fixed interval                                          |
-| `cron`  | `--cron`  | 5-field or 6-field cron expression with optional `--tz` |
-
-Timestamps without a timezone are treated as UTC. Add `--tz America/New_York` for local wall-clock scheduling.
-
-Recurring top-of-hour expressions are automatically staggered by up to 5 minutes to reduce load spikes. Use `--exact` to force precise timing or `--stagger 30s` for an explicit window.
-
-### Day-of-month and day-of-week use OR logic
-
-Cron expressions are parsed by [croner](https://github.com/Hexagon/croner). When both the day-of-month and day-of-week fields are non-wildcard, croner matches when **either** field matches — not both. This is standard Vixie cron behavior.
-
-```
-# Intended: "9 AM on the 15th, only if it's a Monday"
-# Actual:   "9 AM on every 15th, AND 9 AM on every Monday"
-0 9 15 * 1
-```
-
-This fires ~5–6 times per month instead of 0–1 times per month. FengMing uses Croner's default OR behavior here. To require both conditions, use Croner's `+` day-of-week modifier (`0 9 15 * +1`) or schedule on one field and guard the other in your job's prompt or command.
-
-## Execution styles
-
-| Style           | `--session` value   | Runs in                  | Best for                        |
-| --------------- | ------------------- | ------------------------ | ------------------------------- |
-| Main session    | `main`              | Dedicated cron wake lane | Reminders, system events        |
-| Isolated        | `isolated`          | Dedicated `cron:<jobId>` | Reports, background chores      |
-| Current session | `current`           | Bound at creation time   | Context-aware recurring work    |
-| Custom session  | `session:custom-id` | Persistent named session | Workflows that build on history |
-
-<AccordionGroup>
-  <Accordion title="Main session vs isolated vs custom">
-    **Main session** jobs enqueue a system event into a cron-owned run lane and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). They can use the target main session's last delivery context for replies, but they do not append routine cron turns to the human chat lane and do not extend daily/idle reset freshness for the target session. **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
-
-    Main-session cron events are self-contained system-event reminders. They do
-    not automatically include the default heartbeat prompt's "Read
-    HEARTBEAT.md" instruction. If a recurring reminder should consult
-    `HEARTBEAT.md`, say that explicitly in the cron event text or in the
-    agent's own instructions.
-
-  </Accordion>
-  <Accordion title="What 'fresh session' means for isolated jobs">
-    For isolated jobs, "fresh session" means a new transcript/session id for each run. FengMing may carry safe preferences such as thinking/fast/verbose settings, labels, and explicit user-selected model/auth overrides, but it does not inherit ambient conversation context from an older cron row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:<id>` when a recurring job should deliberately build on the same conversation context.
-  </Accordion>
-  <Accordion title="Runtime cleanup">
-    For isolated jobs, runtime teardown now includes best-effort browser cleanup for that cron session. Cleanup failures are ignored so the actual cron result still wins.
-
-    Isolated cron runs also dispose any bundled MCP runtime instances created for the job through the shared runtime-cleanup path. This matches how main-session and custom-session MCP clients are torn down, so isolated cron jobs do not leak stdio child processes or long-lived MCP connections across runs.
-
-  </Accordion>
-  <Accordion title="Subagent and Discord delivery">
-    When isolated cron runs orchestrate subagents, delivery also prefers the final descendant output over stale parent interim text. If descendants are still running, FengMing suppresses that partial parent update instead of announcing it.
-
-    For text-only Discord announce targets, FengMing sends the canonical final assistant text once instead of replaying both streamed/intermediate text payloads and the final answer. Media and structured Discord payloads are still delivered as separate payloads so attachments and components are not dropped.
-
-  </Accordion>
-</AccordionGroup>
-
-### Payload options for isolated jobs
-
-<ParamField path="--message" type="string" required>
-  Prompt text (required for isolated).
-</ParamField>
-<ParamField path="--model" type="string">
-  Model override; uses the selected allowed model for the job.
-</ParamField>
-<ParamField path="--thinking" type="string">
-  Thinking level override.
-</ParamField>
-<ParamField path="--light-context" type="boolean">
-  Skip workspace bootstrap file injection.
-</ParamField>
-<ParamField path="--tools" type="string">
-  Restrict which tools the job can use, for example `--tools exec,read`.
-</ParamField>
-
-`--model` uses the selected allowed model as that job's primary model. It is not the same as a chat-session `/model` override: configured fallback chains still apply when the job primary fails. If the requested model is not allowed or cannot be resolved, cron fails the run with an explicit validation error instead of silently falling back to the job's agent/default model selection.
-
-Cron jobs can also carry payload-level `fallbacks`. When present, that list replaces the configured fallback chain for the job. Use `fallbacks: []` in the job payload/API when you want a strict cron run that tries only the selected model. If a job has `--model` but neither payload nor configured fallbacks, FengMing passes an explicit empty fallback override so the agent primary is not appended as a hidden extra retry target.
-
-Local-provider preflight checks walk configured fallbacks before marking a cron run `skipped`; `fallbacks: []` keeps that preflight path strict.
-
-Model-selection precedence for isolated jobs is:
-
-1. Gmail hook model override (when the run came from Gmail and that override is allowed)
-2. Per-job payload `model`
-3. User-selected stored cron session model override
-4. Agent/default model selection
-
-Fast mode follows the resolved live selection too. If the selected model config has `params.fastMode`, isolated cron uses that by default. A stored session `fastMode` override still wins over config in either direction.
-
-If an isolated run hits a live model-switch handoff, cron retries with the switched provider/model and persists that live selection for the active run before retrying. When the switch also carries a new auth profile, cron persists that auth profile override for the active run too. Retries are bounded: after the initial attempt plus 2 switch retries, cron aborts instead of looping forever.
-
-Before an isolated cron run enters the agent runner, FengMing checks reachable local provider endpoints for configured `api: "ollama"` and `api: "openai-completions"` providers whose `baseUrl` is loopback, private-network, or `.local`. If that endpoint is down, the run is recorded as `skipped` with a clear provider/model error instead of starting a model call. The endpoint result is cached for 5 minutes, so many due jobs using the same dead local Ollama, vLLM, SGLang, or LM Studio server share one small probe instead of creating a request storm. Skipped provider-preflight runs do not increment execution-error backoff; enable `failureAlert.includeSkipped` when you want repeated skip notifications.
-
-## Delivery and output
-
-| Mode       | What happens                                                        |
-| ---------- | ------------------------------------------------------------------- |
-| `announce` | Fallback-deliver final text to the target if the agent did not send |
-| `webhook`  | POST finished event payload to a URL                                |
-| `none`     | No runner fallback delivery                                         |
-
-Use `--announce --channel telegram --to "-1001234567890"` for channel delivery. For Telegram forum topics, use `-1001234567890:topic:123`; FengMing also accepts the Telegram-owned `-1001234567890:123` shorthand. Direct RPC/config callers may pass `delivery.threadId` as a string or number. Slack/Discord/Mattermost targets should use explicit prefixes (`channel:<id>`, `user:<id>`). Matrix room IDs are case-sensitive; use the exact room ID or `room:!room:server` form from Matrix.
-
-When announce delivery uses `channel: "last"` or omits `channel`, a provider-prefixed target such as `telegram:123` can select the channel before cron falls back to session history or a single configured channel. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the target prefix must name the same provider; for example, `channel: "whatsapp"` with `to: "telegram:123"` is rejected instead of letting WhatsApp interpret the Telegram ID as a phone number. Target-kind and service prefixes such as `channel:<id>`, `user:<id>`, `imessage:<handle>`, and `sms:<number>` remain channel-owned target syntax, not provider selectors.
-
-For isolated jobs, chat delivery is shared. If a chat route is available, the agent can use the `message` tool even when the job uses `--no-deliver`. If the agent sends to the configured/current target, FengMing skips the fallback announce. Otherwise `announce`, `webhook`, and `none` only control what the runner does with the final reply after the agent turn.
-
-When an agent creates an isolated reminder from an active chat, FengMing stores the preserved live delivery target for the fallback announce route. Internal session keys may be lowercase; provider delivery targets are not reconstructed from those keys when current chat context is available.
-
-Implicit announce delivery uses configured channel allowlists to validate and reroute stale targets. DM pairing-store approvals are not fallback automation recipients; set `delivery.to` or configure the channel `allowFrom` entry when a scheduled job should proactively send to a DM.
-
-## Output language
-
-Cron jobs do not infer a reply language from channel, locale, or previous
-messages. Put the language rule in the scheduled message or template:
-
-```bash
-fengming cron edit <jobId> \
-  --message "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."
-```
-
-For template files, keep the language instruction in the rendered prompt and
-verify placeholders such as `{{language}}` are filled before the job runs. If
-the output mixes languages, make the rule explicit, for example: "Use Chinese
-for narrative text and keep technical terms in English."
-
-Failure notifications follow a separate destination path:
-
-- `cron.failureDestination` sets a global default for failure notifications.
-- `job.delivery.failureDestination` overrides that per job.
-- If neither is set and the job already delivers via `announce`, failure notifications now fall back to that primary announce target.
-- `delivery.failureDestination` is only supported on `sessionTarget="isolated"` jobs unless the primary delivery mode is `webhook`.
-- `failureAlert.includeSkipped: true` opts a job or global cron alert policy into repeated skipped-run alerts. Skipped runs keep a separate consecutive skip counter, so they do not affect execution-error backoff.
-
-## CLI examples
-
-<Tabs>
-  <Tab title="One-shot reminder">
-    ```bash
-    fengming cron add \
-      --name "Calendar check" \
-      --at "20m" \
-      --session main \
-      --system-event "Next heartbeat: check calendar." \
-      --wake now
-    ```
-  </Tab>
-  <Tab title="Recurring isolated job">
-    ```bash
-    fengming cron create "0 7 * * *" \
-      "Summarize overnight updates." \
-      --name "Morning brief" \
-      --tz "America/Los_Angeles" \
-      --session isolated \
-      --announce \
-      --channel slack \
-      --to "channel:C1234567890"
-    ```
-  </Tab>
-  <Tab title="Model and thinking override">
-    ```bash
-    fengming cron add \
-      --name "Deep analysis" \
-      --cron "0 6 * * 1" \
-      --tz "America/Los_Angeles" \
-      --session isolated \
-      --message "Weekly deep analysis of project progress." \
-      --model "opus" \
-      --thinking high \
-      --announce
-    ```
-  </Tab>
-  <Tab title="Webhook output">
-    ```bash
-    fengming cron create "0 18 * * 1-5" \
-      "Summarize today's deploys as JSON." \
-      --name "Deploy digest" \
-      --webhook "https://example.invalid/fengming/cron"
-    ```
-  </Tab>
-</Tabs>
-
-## Webhooks
-
-Gateway can expose HTTP webhook endpoints for external triggers. Enable in config:
-
-```json5
-{
-  hooks: {
-    enabled: true,
-    token: "shared-secret",
-    path: "/hooks",
-  },
-}
-```
-
-### Authentication
-
-Every request must include the hook token via header:
-
-- `Authorization: Bearer <token>` (recommended)
-- `x-fengming-token: <token>`
-
-Query-string tokens are rejected.
-
-<AccordionGroup>
-  <Accordion title="POST /hooks/wake">
-    Enqueue a system event for the main session:
-
-    ```bash
-    curl -X POST http://127.0.0.1:18789/hooks/wake \
-      -H 'Authorization: Bearer SECRET' \
-      -H 'Content-Type: application/json' \
-      -d '{"text":"New email received","mode":"now"}'
-    ```
-
-    <ParamField path="text" type="string" required>
-      Event description.
-    </ParamField>
-    <ParamField path="mode" type="string" default="now">
-      `now` or `next-heartbeat`.
-    </ParamField>
-
-  </Accordion>
-  <Accordion title="POST /hooks/agent">
-    Run an isolated agent turn:
-
-    ```bash
-    curl -X POST http://127.0.0.1:18789/hooks/agent \
-      -H 'Authorization: Bearer SECRET' \
-      -H 'Content-Type: application/json' \
-      -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4"}'
-    ```
-
-    Fields: `message` (required), `name`, `agentId`, `wakeMode`, `deliver`, `channel`, `to`, `model`, `fallbacks`, `thinking`, `timeoutSeconds`.
-
-  </Accordion>
-  <Accordion title="Mapped hooks (POST /hooks/<name>)">
-    Custom hook names are resolved via `hooks.mappings` in config. Mappings can transform arbitrary payloads into `wake` or `agent` actions with templates or code transforms.
-  </Accordion>
-</AccordionGroup>
-
-<Warning>
-Keep hook endpoints behind loopback, tailnet, or trusted reverse proxy.
-
-- Use a dedicated hook token; do not reuse gateway auth tokens.
-- Keep `hooks.path` on a dedicated subpath; `/` is rejected.
-- Set `hooks.allowedAgentIds` to limit which effective agent a hook can target, including the default agent when `agentId` is omitted.
-- Keep `hooks.allowRequestSessionKey=false` unless you require caller-selected sessions.
-- If you enable `hooks.allowRequestSessionKey`, also set `hooks.allowedSessionKeyPrefixes` to constrain allowed session key shapes.
-- Hook payloads are wrapped with safety boundaries by default.
-
-</Warning>
-
-## Gmail PubSub integration
-
-Wire Gmail inbox triggers to FengMing via Google PubSub.
-
-<Note>
-**Prerequisites:** `gcloud` CLI, `gog` (gogcli), FengMing hooks enabled, Tailscale for the public HTTPS endpoint.
-</Note>
-
-### Wizard setup (recommended)
-
-```bash
-fengming webhooks gmail setup --account fengming@gmail.com
-```
-
-This writes `hooks.gmail` config, enables the Gmail preset, and uses Tailscale Funnel for the push endpoint.
-
-### Gateway auto-start
-
-When `hooks.enabled=true` and `hooks.gmail.account` is set, the Gateway starts `gog gmail watch serve` on boot and auto-renews the watch. Set `FENGMING_SKIP_GMAIL_WATCHER=1` to opt out.
-
-### Manual one-time setup
-
-<Steps>
-  <Step title="Select the GCP project">
-    Select the GCP project that owns the OAuth client used by `gog`:
-
-    ```bash
-    gcloud auth login
-    gcloud config set project <project-id>
-    gcloud services enable gmail.googleapis.com pubsub.googleapis.com
-    ```
-
-  </Step>
-  <Step title="Create topic and grant Gmail push access">
-    ```bash
-    gcloud pubsub topics create gog-gmail-watch
-    gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
-      --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
-      --role=roles/pubsub.publisher
-    ```
-  </Step>
-  <Step title="Start the watch">
-    ```bash
-    gog gmail watch start \
-      --account fengming@gmail.com \
-      --label INBOX \
-      --topic projects/<project-id>/topics/gog-gmail-watch
-    ```
-  </Step>
-</Steps>
-
-### Gmail model override
-
-```json5
-{
-  hooks: {
-    gmail: {
-      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
-      thinking: "off",
-    },
-  },
-}
-```
-
-## Managing jobs
-
-```bash
-# List all jobs
-fengming cron list
-
-# Get one stored job as JSON
-fengming cron get <jobId>
-
-# Show one job, including resolved delivery route
-fengming cron show <jobId>
-
-# Edit a job
-fengming cron edit <jobId> --message "Updated prompt" --model "opus"
-
-# Force run a job now
-fengming cron run <jobId>
-
-# Force run a job now and wait for its terminal status
-fengming cron run <jobId> --wait --wait-timeout 10m --poll-interval 2s
-
-# Run only if due
-fengming cron run <jobId> --due
-
-# View run history
-fengming cron runs --id <jobId> --limit 50
-
-# View one exact run
-fengming cron runs --id <jobId> --run-id <runId>
-
-# Delete a job
-fengming cron remove <jobId>
-
-# Agent selection (multi-agent setups)
-fengming cron create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent ops
-fengming cron edit <jobId> --clear-agent
-```
-
-`fengming cron run <jobId>` returns after enqueueing the manual run. Use `--wait` for shutdown hooks, maintenance scripts, or other automation that must block until the queued run finishes. Wait mode polls the exact returned `runId`; it exits `0` for status `ok` and non-zero for `error`, `skipped`, or a wait timeout.
-
-`fengming cron create` is an alias for `fengming cron add`, and new jobs can use a positional schedule (`"0 9 * * 1"`, `"every 1h"`, `"20m"`, or an ISO timestamp) followed by a positional agent prompt. Use `--webhook <url>` on `cron add|create` or `cron edit` to POST the finished run payload to an HTTP endpoint. Webhook delivery cannot be combined with chat delivery flags such as `--announce`, `--channel`, `--to`, `--thread-id`, or `--account`.
-
-<Note>
-Model override note:
-
-- `fengming cron add|edit --model ...` changes the job's selected model.
-- If the model is allowed, that exact provider/model reaches the isolated agent run.
-- If it is not allowed or cannot be resolved, cron fails the run with an explicit validation error.
-- Configured fallback chains still apply because cron `--model` is a job primary, not a session `/model` override.
-- Payload `fallbacks` replaces configured fallbacks for that job; `fallbacks: []` disables fallback and makes the run strict.
-- A plain `--model` with no explicit or configured fallback list does not fall through to the agent primary as a silent extra retry target.
-
-</Note>
-
-## Configuration
-
-```json5
-{
-  cron: {
-    enabled: true,
-    store: "~/.fengming/cron/jobs.json",
-    maxConcurrentRuns: 8,
-    retry: {
-      maxAttempts: 3,
-      backoffMs: [60000, 120000, 300000],
-      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
-    },
-    webhookToken: "replace-with-dedicated-webhook-token",
-    sessionRetention: "24h",
-    runLog: { maxBytes: "2mb", keepLines: 2000 },
-  },
-}
-```
-
-`maxConcurrentRuns` limits both scheduled cron dispatch and isolated agent-turn execution, and defaults to 8. Isolated cron agent turns use the queue's dedicated `cron-nested` execution lane internally, so raising this value lets independent cron LLM runs progress in parallel instead of only starting their outer cron wrappers. The shared non-cron `nested` lane is not widened by this setting.
-
-The runtime state sidecar is derived from `cron.store`: a `.json` store such as `~/clawd/cron/jobs.json` uses `~/clawd/cron/jobs-state.json`, while a store path without a `.json` suffix appends `-state.json`.
-
-If you hand-edit `jobs.json`, leave `jobs-state.json` out of source control. FengMing uses that sidecar for pending slots, active markers, last-run metadata, and the schedule identity that tells the scheduler when an externally edited job needs a fresh `nextRunAtMs`.
-
-Disable cron: `cron.enabled: false` or `FENGMING_SKIP_CRON=1`.
-
-<AccordionGroup>
-  <Accordion title="Retry behavior">
-    **One-shot retry**: transient errors (rate limit, overload, network, server error) retry up to 3 times with exponential backoff. Permanent errors disable immediately.
-
-    **Recurring retry**: exponential backoff (30s to 60m) between retries. Backoff resets after the next successful run.
-
-  </Accordion>
-  <Accordion title="Maintenance">
-    `cron.sessionRetention` (default `24h`) prunes isolated run-session entries. `cron.runLog.maxBytes` / `cron.runLog.keepLines` auto-prune run-log files.
-  </Accordion>
-</AccordionGroup>
-
-## Troubleshooting
-
-### Command ladder
-
-```bash
-fengming status
-fengming gateway status
-fengming cron status
-fengming cron list
-fengming cron runs --id <jobId> --limit 20
-fengming system heartbeat last
-fengming logs --follow
-fengming doctor
-```
-
-<AccordionGroup>
-  <Accordion title="Cron not firing">
-    - Check `cron.enabled` and `FENGMING_SKIP_CRON` env var.
-    - Confirm the Gateway is running continuously.
-    - For `cron` schedules, verify timezone (`--tz`) vs the host timezone.
-    - `reason: not-due` in run output means manual run was checked with `fengming cron run <jobId> --due` and the job was not due yet.
-
-  </Accordion>
-  <Accordion title="Cron fired but no delivery">
-    - Delivery mode `none` means no runner fallback send is expected. The agent can still send directly with the `message` tool when a chat route is available.
-    - Delivery target missing/invalid (`channel`/`to`) means outbound was skipped.
-    - For Matrix, copied or legacy jobs with lowercased `delivery.to` room IDs can fail because Matrix room IDs are case-sensitive. Edit the job to the exact `!room:server` or `room:!room:server` value from Matrix.
-    - Channel auth errors (`unauthorized`, `Forbidden`) mean delivery was blocked by credentials.
-    - If the isolated run returns only the silent token (`NO_REPLY` / `no_reply`), FengMing suppresses direct outbound delivery and also suppresses the fallback queued summary path, so nothing is posted back to chat.
-    - If the agent should message the user itself, check that the job has a usable route (`channel: "last"` with a previous chat, or an explicit channel/target).
-
-  </Accordion>
-  <Accordion title="Cron or heartbeat appears to prevent /new-style rollover">
-    - Daily and idle reset freshness is not based on `updatedAt`; see [Session management](/concepts/session#session-lifecycle).
-    - Cron wakeups, heartbeat runs, exec notifications, and gateway bookkeeping may update the session row for routing/status, but they do not extend `sessionStartedAt` or `lastInteractionAt`.
-    - For legacy rows created before those fields existed, FengMing can recover `sessionStartedAt` from the transcript JSONL session header when the file is still available. Legacy idle rows without `lastInteractionAt` use that recovered start time as their idle baseline.
-
-  </Accordion>
-  <Accordion title="Timezone gotchas">
-    - Cron without `--tz` uses the gateway host timezone.
-    - `at` schedules without timezone are treated as UTC.
-    - Heartbeat `activeHours` uses configured timezone resolution.
-
-  </Accordion>
-</AccordionGroup>
-
-## Related
-
-- [Automation](/automation) — all automation mechanisms at a glance
-- [Background Tasks](/automation/tasks) — task ledger for cron executions
-- [Heartbeat](/gateway/heartbeat) — periodic main-session turns
-- [Timezone](/concepts/timezone) — timezone configuration

package/docs/automation/cron-vs-heartbeat.md

@@ -1,11 +0,0 @@
----
-summary: "Redirect to /automation"
-title: "Cron vs heartbeat"
----
-
-The decision guide for cron vs heartbeat lives under [Automation](/automation).
-
-## Related
-
-- [Scheduled tasks](/automation/cron-jobs)
-- [Background tasks](/automation/tasks)

package/docs/automation/gmail-pubsub.md

@@ -1,11 +0,0 @@
----
-summary: "Redirect to /automation/cron-jobs"
-title: "Gmail PubSub"
----
-
-This page moved to [Scheduled Tasks](/automation/cron-jobs#gmail-pubsub-integration). See [Scheduled Tasks](/automation/cron-jobs#gmail-pubsub-integration) for Gmail PubSub documentation.
-
-## Related
-
-- [Webhook](/automation/webhook)
-- [Automation troubleshooting](/automation/troubleshooting)