docs(cron): document job API and launch statuses

[w3lld1]

Summary

I corrected the Cron button's location and settings path, filled in the two missing run statuses, and clarified that launch/prompt-delivery history does not report task success.

I documented all nine existing cron endpoints in the API reference and wiki, including request fields, response payloads, versioned aliases, partial updates, ownership restrictions, and asynchronous prompt delivery. I also added documentation checks against the route declarations, job schema, and status type. I did not change runtime behavior.

Fixes #587

Validation

I ran:

• npm test -- test/cron-docs.test.ts test/cron-time.test.ts — 17 tests passed across two files, including three new documentation checks.
• npm run typecheck
• npm run lint
• npm run format:check
• npm run check:frontend-syntax
• npm run check:browser-excludes
• npx prettier --check test/cron-docs.test.ts
• git diff --check origin/master...HEAD

My initial npm ci stopped while node-gyp extracted node-pty's Node headers (fchown: EINVAL). I installed dependencies with npm ci --ignore-scripts for the checks above. I left the full unit/integration suite, native dependency build, and server boot smoke test to upstream CI; I am not claiming they passed locally.

[Ark0N]

Great thanks and welcome :-)

[Ark0N]

Thanks a lot @w3lld1, and welcome! This PR fixes the Cron button location and settings path on the Cron Jobs page, fills in the two missing run statuses, documents all nine cron endpoints in the API reference and the HTTP API wiki page, and adds a test that keeps those docs tied to the routes, the schema and the status type. I checked every claim against cron-routes.ts, schemas.ts and cron-service.ts and they hold up, and the new test fails exactly where it should when a row goes missing.

A few small things:

1. The old "header button" wording is still on two other pages. docs/wiki/The-Dashboard.md:257 says the Cron panel opens from "Header (opt-in)", and docs/cron-guide.md:8 and :27 say the button is in the header. The Cron Jobs page links to cron-guide.md as the complete reference, so please change those three to the bottom toolbar as well. (My issue only named the one page, so that is on me.)
2. session_started is not always followed by a later status (docs/api-reference.md:156, docs/wiki/Cron-Jobs.md:102). If the session is closed during the readiness wait, or the server restarts before delivery, sendPromptWhenReady in src/cron/cron-service.ts (lines 637, 649, 659) returns without failing the run, so it keeps session_started with finishedAt: null for good. One sentence saying so would stop a client from polling forever.
3. Run Now also closes the previous run's session (docs/api-reference.md:138). For a recurring job with autoClosePreviousSession at its default, Run Now closes the session left by the job's previous run before launching (cron-service.ts:428, pinned in test/cron-service.test.ts:642). Worth adding to the Run Now paragraph, since an API caller could otherwise kill a session that is still working.

Optional nits, take them or leave them:

• docs/api-reference.md:123: promptFilePath must be an absolute path (safePathSchema), so "absolute path inside workingDir" avoids a confusing validation error.
• docs/api-reference.md:162: write 403 FORBIDDEN, as the CLI management and MCP sync sections do, since the error-code table above does not list it.
• docs/api-reference.md:146: lastDueKey is an internal duplicate-launch guard; calling it opaque keeps its format free to change.
• A link from the new reference section to docs/cron-guide.md (it also lists the cron:runCreated / cron:runUpdated SSE events) would help readers and keep the copies from drifting.
• test/cron-docs.test.ts:39 matches a hard line break inside a sentence, so a reflow breaks it; a short header comment saying what the test guards would match the other docs tests.

None of this blocks the PR. I am happy to apply these on top at merge time, or you can push them here first if you prefer, and then it goes in.

[w3lld1]

Addressed the three follow-up points and the optional nits in 34439d1:

• The linked dashboard and complete guide now put Cron in the bottom toolbar.
• Both the API reference and Cron Jobs page explain that a run can remain session_started indefinitely with finishedAt: null after session removal during readiness or a server restart before delivery.
• Run Now's previous-session closure is explicit, including the risk of closing a still-working session.
• Clarified the absolute prompt-file path, 403 FORBIDDEN, opaque lastDueKey, and linked the complete guide/SSE events. The docs test now tolerates sentence reflow, has a file overview, and checks the linked pages and history caveat.

Fresh checks on the committed head:

• npm test -- test/cron-docs.test.ts test/cron-time.test.ts --maxWorkers=2 — 18 passed.
• npx --no-install prettier --check test/cron-docs.test.ts
• git diff HEAD^ HEAD --check

The five documented static gates also passed: typecheck, lint, format:check, check:frontend-syntax, and check:browser-excludes. Dependencies were installed with npm ci --ignore-scripts; the full suite, native build, server smoke test, and real scheduled-session scenario were not run in this follow-up. No runtime behavior changed.

AI disclosure: this follow-up was generated and checked by Hermes using OpenAI gpt-6.1-sol; it is not a claim of personal human verification.

[Ark0N]

Merged, thank you @w3lld1! This closes #587, and the wiki pages go live on the GitHub wiki with this push (the wiki sync runs on every master push that touches docs/wiki/). The changes ship in the next release, and you'll be in its Thanks section.

What made this an easy merge: every claim checks out against cron-routes.ts, schemas.ts and cron-service.ts, and your follow-up went past what I asked for. The non-terminal session_started caveat and the Run Now auto-close note are the two things an API caller would trip over first. test/cron-docs.test.ts is the part I value most, since it ties the docs to the route table, the job schema and the status type, so the next cron route or status that lands without docs fails CI instead of drifting quietly.

A related PR (#597) also targeted #587; it was closed as a duplicate of this one, since yours came first and covered more.

Thanks as well for the clear validation notes and the AI disclosure: knowing exactly what was and wasn't run locally made the review faster.