chore(plan-exec): 2026-07-17-cron-trigger — phase "Phase 5: Verification surface, contract test, docs & spec hygiene" passed gates

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGgfho2J6YfRSQN1bSDhj6

Author: edgehero

.env.example

@@ -21,6 +21,8 @@ PI_CONCURRENCY=3       # how many jobs run in parallel
 VALKEY_URL=redis://127.0.0.1:6379
 PI_JOB_IMAGE=pi-job:latest          # the image you built:  docker build -f image/Dockerfile -t pi-job:latest .
 # PI_JOBS_DIR=                      # where per-job /job inputs live (default: your OS temp dir)
+# PI_SCHEDULES_FILE=                # ABSOLUTE path to schedules.json; unset disables cron (a relative path resolves against the worker's WorkingDirectory)
+PI_SCHEDULER_STALL_MAX=2            # tear down a scheduler after N consecutive stalls (money backstop)
 
 # --- GitHub trigger (receiver + worker auth) ---
 # Webhook receiver

.github/workflows/pi-upgrade-check.yml

@@ -107,7 +107,13 @@ jobs:
       # PI_DISPATCH_REQUIRE_*_TESTS=1 turns a skip into a hard failure. A skipped assertion is an
       # UNVERIFIED assertion, and "skipped = pass" is precisely the reasoning that lets a
       # guardrail-less agent ship green. VALKEY_TEST_URL activates the queue integration test.
-      - name: Contract tests -- guardrails, -nc, exit codes, env allowlist, queue, receiver enqueue (all required)
+      #
+      # Cron/scheduler assumptions this run pins (BullMQ 5.80.4), each SILENT if it drifts:
+      #   - no-backfill / no-overlap / deterministic repeat: jobId  -> specs/design.md:206-216
+      #   - must-handle -10/-11 (schedule edit else silent no-op)   -> specs/design.md:231
+      #   - scheduler jobs bypass maxStalledCount (stall carve-out)  -> specs/constitution.md:203-216
+      # Exercised by worker/test/cron.integration.test.mjs (VALKEY_TEST_URL + PI_DISPATCH_REQUIRE_WORKER_TESTS gate it live).
+      - name: Contract tests -- guardrails, -nc, exit codes, env allowlist, queue, receiver enqueue, cron (all required)
         env:
           PI_DISPATCH_REQUIRE_LOADER_TESTS: "1"
           PI_DISPATCH_REQUIRE_WORKER_TESTS: "1"

.gitignore

@@ -29,6 +29,11 @@ coverage/
 .env.*
 !.env.example
 
+# Cron schedule list. Holds host paths and per-schedule tasks; the committed
+# schedules.example.json is the template.
+schedules.json
+!schedules.example.json
+
 # Python — bytecode and tool caches from the skill scripts under .claude/skills/
 __pycache__/
 *.py[cod]

README.md

@@ -72,6 +72,32 @@ flowchart LR
 
 Read [`SECURITY.md`](SECURITY.md) before you rely on it — it states plainly what is and is not defended.
 
+## Scheduling recurring jobs
+
+A cron schedule is a trigger, not a new job kind: each entry runs a local folder through a flow on a cron
+pattern. Cron is **off by default** — the worker reads schedules only when `PI_SCHEDULES_FILE` points at a
+file.
+
+```bash
+# 1. Copy the template and edit it
+cp schedules.example.json schedules.json   # then edit "folder" to a REAL absolute path
+
+# 2. Point the worker at it (absolute path), and restart the worker
+#    In .env:  PI_SCHEDULES_FILE=/absolute/path/to/schedules.json
+npx pi-dispatch worker
+```
+
+Each entry sets `id`, `cron` (5 or 6 fields), `folder`, `flow`, and `task`; `provider`, `model`, and
+`maxTurns` are optional and fall back to the worker's defaults. A schedule's `folder` is a **host path** —
+the worker runs on the host ([`DES-WORKER-ON-HOST`](specs/design.md)) and mounts that folder into the job
+container, so it must be readable by the worker's user.
+
+- **Local schedules only this slice.** `kind` must be `"local"`; the loader rejects `kind:"github"` at
+  startup — a schedule has no webhook delivery, issue number, or body to work.
+- **Editing `folder` is mandatory.** Copying `schedules.example.json` verbatim makes the worker **refuse
+  to start** with `configError: folder does not exist` until `folder` names a real path. This is
+  fail-loud on purpose: a broken schedule never silently fails to fire.
+
 ## Advanced: GitHub automation
 
 pi-dispatch can also be triggered by GitHub — label an issue, and a container works it on a fresh clone,
@@ -132,9 +158,9 @@ minutes.
 
 ## Status
 
-The local-folder path (image, worker, `pi-dispatch run` / `worker`) and the GitHub webhook path
-(receiver → queue → clone → PR) are built and work. The admin panel and scheduled (cron) triggers are in
-progress. The design is specified in
+The local-folder path (image, worker, `pi-dispatch run` / `worker`), the GitHub webhook path
+(receiver → queue → clone → PR), and scheduled (cron) triggers for local folders are built and work. The
+admin panel is in progress. The design is specified in
 [`specs/`](specs/) — start with [`specs/constitution.md`](specs/constitution.md) for the non-negotiables
 and [`specs/design.md`](specs/design.md) for the decisions and what was rejected.
 

schedules.example.json

@@ -0,0 +1,15 @@
+{
+  "schedules": [
+    {
+      "id": "nightly-tidy",
+      "kind": "local",
+      "cron": "0 3 * * *",
+      "folder": "/absolute/path/to/your/project",
+      "flow": "tidy",
+      "task": "dedupe imports and run the formatter",
+      "provider": "anthropic",
+      "model": "claude-sonnet-4-5-20250929",
+      "maxTurns": 30
+    }
+  ]
+}

specs/design.md

@@ -214,6 +214,15 @@ money with no upstream turn limit (`REQ-RUNNER-TURN-BUDGET`).
     one under load, so the panel should surface `next` drift rather than let it look healthy.
   - **Deterministic `jobId`** — `repeat:<schedulerId>:<nextMillis>` — so scheduler jobs get
     `REQ-DEDUP-BY-DELIVERY-GUID`-equivalent dedup for free, with no GUID to supply.
+  - **Local-only this slice.** A `kind:"github"` schedule is rejected at load. A scheduled GitHub job has
+    no webhook delivery, issue number, title, or body to supply, and post-integration the github path would
+    perform a real host clone and per-job token mint before failing every tick — spend and side effects for
+    a trigger that cannot complete. GitHub scheduling is deferred to a later slice.
+  - **Two distinct enqueue paths, not duplication.** The interactive `enqueueLocalJob` sets `attempts: 2`
+    with backoff; the scheduled path (`upsertJobScheduler`) passes retention-only opts with a single
+    attempt. For an unattended recurring trigger the **cadence is the retry**, so a failing tick must not
+    multiply spend within one tick — two distinct triggers with different retry semantics, not two
+    implementations of one thing.
   **Legacy `repeat:` is deprecated and slated for removal in v6** — starting on it would be adopting a
   known-dead API.
 - **Evidence (upstream)**: `taskforcesh/bullmq @ v5.80.4 → src/classes/queue.ts:468-495 → upsertJobScheduler`

specs/interfaces.md

@@ -468,12 +468,41 @@ Evidence convention as in `constitution.md`.
 - **Traces to**: `CONST-HMAC-OVER-RAW-BODY`, `REQ-TRIGGER-AUTHOR-GATE`, `REQ-DEDUP-BY-DELIVERY-GUID`
 - **Acceptance**: Given a payload with unknown extra fields, behaviour is unchanged.
 
+## INT-SCHEDULES-FILE-CONTRACT
+
+**operator → worker.**
+
+- **Contract**:
+  ```
+  schedules.json  (path via PI_SCHEDULES_FILE; absolute; unset = cron disabled)
+  { "schedules": [
+    { "id": "<[A-Za-z0-9._-]+, no ':' , unique>",
+      "kind": "local",                     // only "local"; "github" rejected at load
+      "cron": "<5 or 6 space-separated fields>",
+      "folder": "<absolute HOST path, must exist>",
+      "flow": "<flow name>",
+      "task": "<operator-authored prompt text — DATA, lands in /job/prompt.md>",
+      "provider": "<optional>", "model": "<optional>", "maxTurns": <optional> } ] }
+  ```
+- **Why**: The operator's schedule set is a host file — diffable, reviewable, and git-trackable — rather
+  than API state, so a schedule change is a reviewed edit. `id` must be `:`-free because the stall guard
+  parses BullMQ's deterministic `repeat:<id>:<millis>` job id by splitting on `:`; a colon in the id would
+  corrupt that parse. `task` is operator-authored natural language and is therefore **DATA**
+  (`CONST-ISSUE-TEXT-IS-DATA`): it lands in `/job/prompt.md` as the user prompt, never in a system prompt
+  or persona.
+- **Traces to**: `DES-CRON-VIA-BULLMQ-SCHEDULER`, `CONST-ISSUE-TEXT-IS-DATA`
+- **Acceptance**: Given an entry that is malformed, has `kind:"github"`, a duplicate `id`, a `:` in its
+  `id`, or a `folder` that does not exist, when the config loads, then load throws a
+  `piDispatchConfig`-tagged error. Given a valid `local` entry, when it fires, then the emitted job's
+  `data` byte-matches the shape produced by the interactive local (`enqueueLocalJob`) path.
+
 ---
 
 ## Revision History
 
 | Date | Change |
 |---|---|
+| 2026-07-17 | Added INT-SCHEDULES-FILE-CONTRACT, documenting the implemented `schedules.json` host-file shape (`PI_SCHEDULES_FILE`): `local`-only, `:`-free unique `id`, `task` as DATA, and load-time rejection of malformed/`github`/duplicate/missing-folder entries. |
 | 2026-07-15 | Initial. Extracted from `DESIGN.md` v0.1 §5.1, §5.3, §5.4, §5.5. `INT-SDK-SESSION-OPTIONS` is **new** — the source doc left the SDK option set unverified (its §10) and was wrong about the print-mode flag shape and the mode union. `PLAYWRIGHT_BROWSERS_PATH` added to the runtime contract: the source doc's Dockerfile was broken as written for non-root execution. The source doc's code sketches are deliberately **not** carried over — the real Dockerfile and handler are the truth, and a spec that mirrors them drifts on the first commit. |
 | 2026-07-16 | **Correction — "pi never throws" was FALSE**, and it was in this file for a day as the justification for forbidding `try`/`catch` outright. Adversarial re-verification refuted it: `agent-session.ts:1242-1244` is `catch (error) { preflightResult?.(false); throw error; }`, and pi's **own JSDoc** (`:1099-1100`) documents throws on no-model, no-API-key, and missing `streamingBehavior`; `agent.ts:470-471` throws `"Agent is already processing."` outside the lifecycle try entirely. The rule as written would have produced a runner that dies of an unhandled rejection on a missing API key, exiting Node's default `1` = *retryable*, so the queue pays to retry a job that can never succeed. **Both mechanisms are required and cover disjoint sets: preflight throws, the loop swallows.** Also corrected: `StopReason` has **five** values (`packages/ai/src/types.ts:380`) — the entry handled three, and a default branch silently maps `"length"` (truncated output) to success. `reload()` has **no early return** — a second call fully re-runs everything; the earlier "the `loaded` guard makes a double call safe" framing was wrong. The lesson is the file's own: this entry was written from source and still asserted an absolute from a partial read. `INT-CONTAINER-RUNTIME-CONTRACT` gained `--init`, `--shm-size` (explicitly **not** `--ipc=host`, which Playwright recommends but which would share the host IPC namespace with an adversarial container), fonts (absent ⇒ tofu-box screenshots that silently gut `REQ-FRONTEND-VISUAL-VERIFY`), and the fact that **`COPY --chown` does not fix the EACCES trap** because it skips auto-created parent dirs. |
 | 2026-07-15 | `INT-RUNNER-EXIT-CODE-PROTOCOL` gained its **mechanism**, which was the missing half. The codes were right; nothing said how to produce them, and **the obvious implementation produces them wrong**. ~~`pi never throws`~~ (**refuted the next day — see above**): `agent.ts:485-491` catches and `handleRunFailure` does not rethrow, so abort / 429 / 5xx / dead network all resolve `await session.prompt()` normally — and `prompt()` returns `Promise<void>`, so there is no return value either. A `try`/`catch` runner exits `0` on every infrastructure failure: queue records success, never retries, job did nothing — verbatim the worst failure class this project names. The exit code must be derived from `stopReason` on the terminal message, captured via `subscribe()`. Also recorded: the `subscribe()` listener is **sync and unawaited**, so a budget check that awaits will overshoot. `INT-CONTAINER-RUNTIME-CONTRACT` gained two runtime facts that fail *inside the container* where no Dockerfile hints at them: the agent dir must be **writable** by the non-root user (pi lazily writes `auth.json` on first credential touch), and Chromium needs **`--no-sandbox`** because `--cap-drop=ALL` denies it the seccomp/`SYS_ADMIN` its own sandbox requires — the container is the sandbox, and re-granting caps to Chromium would invert the security model. Two cited paths were **dead** (`packages/ai/src/api/env-api-keys.ts`, `packages/coding-agent/src/core/config.ts`); claims and line numbers were correct, only the addresses were wrong — the sneakiest defect class, since it reads as verified and cannot be followed. All cited paths now resolve. Good news recorded too: `before_agent_start` fires strictly before any provider HTTP call, so the assembled-prompt assertion costs **zero tokens**. |

specs/requirements.md

@@ -227,6 +227,40 @@ local), the credential (a short-lived scoped token for GitHub jobs vs none for l
   completion or failure line carrying the job id and outcome; during the run, the container's output is
   visible there.
 
+## REQ-CRON-SCHEDULED-JOBS
+
+- **Statement**: Scheduled jobs shall be driven by BullMQ **Job Schedulers** (`upsertJobScheduler`), one
+  per configured schedule. A schedule is a **trigger, not a job kind**: on each tick it emits an ordinary
+  `kind:"local"` job that flows through the **same** processor as an interactively-triggered local job.
+- **Why**: An unattended recurring trigger spends real money against a paid provider with nobody watching,
+  so every failure mode of the scheduler is a money-or-silence failure. Job Schedulers are a Redis-resident
+  object (survives worker and Redis-under-AOF restart) and give no-backfill and structural no-overlap for
+  free — reimplementing those is the four-mechanism drowning `DES-CRON-VIA-BULLMQ-SCHEDULER` refused. The
+  scheduler is also the one path that **bypasses `maxStalledCount`** (`CONST-RETRY-INFRA-ONLY`), so the
+  stall backstop must be rebuilt explicitly; and because it fires while nobody watches, a `-10`/`-11`
+  silent no-op or an in-tick retry storm would be invisible without the loud-surfacing and no-retry rules
+  below.
+- **Traces to**: `DES-CRON-VIA-BULLMQ-SCHEDULER`, `CONST-RETRY-INFRA-ONLY`, `CONST-BUDGET-BEFORE-TOKENS`,
+  `REQ-RUNNER-TURN-BUDGET`
+- **Acceptance**:
+  - Given a config with N schedules, when the worker loads them, then it calls `upsertJobScheduler` once
+    per schedule; a `-10` (`SchedulerJobIdCollision`) or `-11` (`SchedulerJobSlotsBusy`) result — whether
+    thrown or returned — is surfaced loudly (logged and the load fails), never swallowed into a silent
+    no-op.
+  - Given a scheduler whose per-scheduler stall counter exceeds `PI_SCHEDULER_STALL_MAX`, when the next
+    stall is observed, then the scheduler is torn down via `removeJobScheduler` — the explicit backstop for
+    the `maxStalledCount` carve-out.
+  - Given a worker that was down across one or more due ticks, when it restarts, then exactly one job is
+    emitted (no backfill) and no second job for a schedule is created while that schedule's prior job is
+    still processing (no overlap).
+  - Given a scheduler resident in Redis but absent from the current config, when the worker performs its
+    startup reconcile, then the orphaned scheduler is removed.
+  - Given a schedule entry with `kind:"github"`, when the config loads, then the entry is rejected — a
+    scheduled trigger supplies no webhook delivery, issue number, title, or body, so only `kind:"local"`
+    is admissible.
+  - Given a scheduled occurrence that fails (including an infra fault), when the tick concludes, then the
+    occurrence is **not** retried within the tick — the schedule's own cadence is the retry.
+
 ---
 
 ## Notes (not requirements)
@@ -248,4 +282,5 @@ wait-list working as designed, not a failure — see `README.md`.
 |---|---|
 | 2026-07-15 | Initial. Extracted from `DESIGN.md` v0.1 §1, §5.1–5.2, §5.6, §7, §8. `REQ-RUNNER-TURN-BUDGET` and `REQ-UPSTREAM-CONTRACT-TESTS` are **new** — both exist because source-verification refuted design assumptions the doc had marked "verify". §8's failure-mode table was the richest source; one of its rows ("verify: pi max-turns option") was wrong. |
 | 2026-07-17 | Added REQ-BRANCH-PROTECTION-PRECONDITION, formalizing the branch-protection refusal already enforced in `processor.mjs`/`github-host.mjs` (was a dangling code citation). |
+| 2026-07-17 | Added REQ-CRON-SCHEDULED-JOBS, formalizing the implemented BullMQ Job Scheduler cron path: `local`-only triggers, loud `-10`/`-11` handling, per-scheduler stall teardown, startup orphan reconcile, and no in-tick retry. |
 | 2026-07-16 | **Scope de-GitHub-ified.** It said "triggers on GitHub issue activity" and never mentioned local folders, the CLI/panel, or cron -- stale, since local is now first-class and built. Rewritten as trigger × target. `REQ-JOB-STATUS-COMMENTS` scoped to GitHub jobs explicitly (a local job has no issue). New `REQ-LOCAL-JOB-VISIBILITY`: local jobs surface their outcome on the worker console (and later the panel) -- the local counterpart of the issue comment and the same signal for `CONST-PI-VERSION-PINNED`'s silent-no-op mode. Code updated to match: startWorker now logs one terminal line per job. |