bug: the daily digest must print the repository's scheduled next run, not the interval answer #713

Written-by: Fledge Platform Product

Expected vs actual

One repository, one day, two different next-run answers. The repository page names the instant the scheduler will run it; the daily digest email names a time computed from last_run_at + min(interval_minutes, workCooldownMinutes). The email never reads the repository's schedule row, so for a cron repository the two surfaces disagree by days, and for a disabled repository with no schedule row the email promises a run the page says will never start.

Actual. buildDigest (src/jobs/service.ts:2449) computes the line for every repository with auto_iterate = 1:

2461  const next = Number.isFinite(last) ? new Date(last + Math.min(repo.interval_minutes, this.config.runner.workCooldownMinutes) * 60_000) : new Date()
2462  nextRuns.push({ repo: label, when: next.getTime() <= Date.now() ? '等待调度' : this.digestTime(next) })

rendered as · 下次自动迭代：<repo> · <when> at src/email/templates.ts:371 (text) and :388 (html). Neither line consults store.scheduleForRepo (src/db.ts:4174), repos.enabled (src/db.ts:1018) or the legacy-rule floor.

Untested. That formula has never been asserted: buildDigest has exactly one caller (src/jobs/service.ts:2512) and no reference anywhere under test/. test/digestEmail.test.ts builds nextRuns by hand and asserts the template, so the faulty line is the one part of the sentence no test can see — a red test has to drive jobs.tick(), not the template.

Expected. The same instant the repository page names, computed by the same rule. The page reads the schedule row in the route (src/app.ts:1825–:1826, ScheduledNext at :1888) and prints it through plannedNextLine (src/views/pages.ts:745) → nextRunLine (:728) → nextTime (src/schedules/next.ts:463); the dashboard does the same (src/app.ts:1248–:1257 → src/views/pages.ts:769). docs/architecture.md:107–:113 states the invariant: "One next-run rule … which rule answers is decided by the repository, never by the surface." The digest is a third surface of that rule and today is the only one outside it.

Minimal reproduction

DIGEST_HOUR=0, DIGEST_TIMEZONE=Asia/Shanghai, an approved user with email_daily_digest = 1, one repository o/r with auto_iterate = 1, enabled = 1, interval_minutes = 1440, last_run_at = <now - 10 minutes>, and a saved schedule row { kind: 'cron', expression: '0 9 * * 1-5', timezone: 'Asia/Shanghai' } via store.saveSchedule (src/db.ts:4186). Trigger the pass with jobs.tick() (src/jobs/service.ts:2912), which calls maybeSendDigests() at :3211.

• Repository page prints 2026-11-16 01:00:00 UTC — Monday 09:00 Asia/Shanghai (plannedNextLine formats the planner instant through humanTimeShort, src/lib/time.ts:30).
• Digest email prints the interval answer — last_run_at + 15 minutes, i.e. five minutes after the pass, 11/14 20:57 for a pass at 12:52Z — this evening, instead of Monday (digestTime, src/jobs/service.ts:2438, formats in config.digest.timeZone).

Case 2a, deterministic — disabled with no schedule row. Setup as case 1 but auto_iterate = 1, enabled = 0 and no schedule row: the page prints 仓库已停用，自动运行不会开始 (src/views/pages.ts:730), and the digest still prints a time. store.listRepos (src/db.ts:4122) has no enabled filter, so a disabled repository reaches buildDigest unchanged. Write auto_iterate = 1, enabled = 0 explicitly rather than "same setup with enabled = 0": the /repos/:id/disable route sets both fields to 0 (src/app.ts:3310) and buildDigest emits a line only for auto_iterate === 1 (src/jobs/service.ts:2460), so a repository disabled through that button yields no line at all and the case would assert on an absent line. Only the settings route writes the two fields independently (src/app.ts:3246–:3247).

Case 2b, disabled with a row — the slice must preserve the page, not contradict it. Case 1 plus enabled = 0: the page still prints the planner instant, because the route attaches scheduledNext whenever a schedule row exists (src/app.ts:1884–:1889) and scheduledNext wins over nextRunLine (src/views/pages.ts:1259), so enabled is never consulted for a saved row. The digest must print that same planner instant. This is why the disabled assertion is narrowed to the no-row fixture: a helper that checked enabled before the row would disagree with the page on exactly the disabled-with-row repository, which is the same class of defect this card removes, pointed the other way.

Fixture note for case 1. The digest's 等待调度 branch is emitted when its computed time is <= now, which is exactly the page's due state (src/views/pages.ts:748). A fixture whose last_run_at is old enough that last_run_at + 15m is already past would make the buggy email print 等待调度 and could accidentally agree with a due page. Keep last_run_at inside the cooldown (now - 10m, clamp 15m) so the buggy answer is a future formatted time, and assert the two candidate strings differ before asserting the email carries the planner's one.

Proposed red test

Two existing files, split the way the tree already splits this surface — no new test file.

• test/nextScheduledRun.test.ts owns these assertions today: both precedent commits added their next-run cases there — 10ea236622 (the one-next-run rule) and f859f242 (the schedule row) — and at aa83dc0b the file already covers the cooldown rule (:115), the page and dashboard agreeing (:135), disabled (:144), active job (:151), idle (:158) and "the dashboard answers with the schedule row, not the interval" (:173). The new helper's own cases belong in this file: the planner branch returning { at, state: 'scheduled' } with nextTime's instant for a cron row, unknown-unreadable for a row scheduleFromRow refuses (src/schedules/tick.ts:64), unknown-closed for a window that has ended, and each NextRunState for the interval branch, including disabled, not-ready, idle, active-job, waiting-first-run, plus one case proving not-ready is never reported when config.flybot.instanceImage === '' (the fallback in the shape below). This adds cases to an existing file; it does not narrow or re-open that file's current cases.
• test/jobs.test.ts gets only the three digest integration cases, because it already drives the pass: new Jobs(store, testConfig({ digest: { hour: 0, timeZone: 'Asia/Shanghai' } }), runnerStub, new MemoryMailer()), seed, await jobs.tick(), read mailer.messages — precedent :171 ("daily digests still send while two jobs are active"), so no new seam.

1. Integration, case 1 (cron row). Assert the sent text contains 下次自动迭代：o/r · followed by the digest's own formatter applied to nextTime(scheduleFromRow(row), now) — the expected string is computed in the test with the same Intl options, not hard-coded — and does not contain the string the interval rule produces for the same fixture.
2. Integration, case 2a (no row, enabled = 0). With auto_iterate = 1, enabled = 0 and no schedule row, assert the text carries 仓库已停用，自动运行不会开始 for that repository and no formatted instant.
3. Integration, case 2b (row, enabled = 0). Case 1's fixture plus enabled = 0: assert the text carries the same planner instant case 1 asserts, so the fix cannot start disagreeing with the page on a disabled-but-scheduled repository.

All three integration cases must fail on the unbroken tip and pass with the fix; they assert on message.text, not the html, because :388 escapes and :371 does not.

Shape — the smallest slice: (b), as ruled

The rule's instant already has one home: nextTime (src/schedules/next.ts:463) and the legacy nextRun (src/lib/nextRun.ts:43). What the email cannot reach is the choice between them — that lives in a view module (nextRunLine/plannedNextLine are non-exported functions in src/views/pages.ts, all 10 references are in that file, none outside it), which is why a job module cannot call it.

So: (b), with the wording duplicated and the rule not:

• One new exported function in src/lib/ (e.g. src/lib/nextRunFor.ts) returning { at: number | null; state: <its own union> }. It reuses NextRun (src/lib/nextRun.ts:34) for the interval branch and adds the two schedule-row answers unknown-unreadable and unknown-closed for the planner branch; state for a saved row is due when at <= now else scheduled, exactly src/views/pages.ts:748. Do not add the two new members to NextRunState (src/lib/nextRun.ts:9): nextRunLine (src/views/pages.ts:728) switches on that union exhaustively, so a new member would drag a view change into this slice.
• It takes the facts a caller can already obtain cheaply and that the dashboard route already reads for the same sentence: the repo row, store.scheduleForRepo(repo.id), store.listOpenWorkItems(repo.id) (src/db.ts:4674), store.activeJobForRepo(repo.id) (src/db.ts:4722), and instanceReady computed with the fallback both existing surfaces apply — config.flybot.instanceImage === '' ? true : store.getRepoInstance(repo.id)?.status === 'ready' (src/db.ts:4436; the repository page at src/views/pages.ts:1256 and the dashboard at :782 only report not-ready when an instance image is configured). Passing the raw row status instead would print FlyBot 实例未就绪 for every repository on a deployment with no instance image, which is the same defect in the opposite direction — a second implementation of the rule with one guard missing. No network call, unlike the digest's existing teamState question fetch.
• The interval branch delegates to nextRun() (src/lib/nextRun.ts:43); the schedule branch to scheduleFromRow + nextTime. No second copy of max(15, min(interval, cooldown)): that is dueAfterMs (src/lib/nextRun.ts:39), which the digest currently inlines as Math.min without the floor.
• buildDigest calls it and maps state to its own Chinese sentence, reusing the page's wording where the state exists (src/views/pages.ts:730–:738). src/jobs/ must not import src/views/**; that is what (b) buys. Because the interval branch returns nextRun's own states, the same table also stops the email from printing 等待调度 for a repository that has never run (waiting-first-run) and from printing a time for idle, active-job or not-ready — covered by the helper's unit cases in test/nextScheduledRun.test.ts, not by a third email fixture.

Not (a): moving both view helpers into src/lib/ re-points every reference in src/views/pages.ts — :705 (interface field), :769, :786, :897, :911, :1259, plus the calls inside the pair at :748 — and rewrites the route's ScheduledNext contract, for a one-line email contradiction. (b) is the slice a single session can finish and a reviewer can check.

One consequence of (b) worth stating in the PR body: the choice between the schedule row and the interval rule then has two implementations — the route's (src/app.ts:1248–:1257, :1888) and the helper's — while the instant itself stays single-sourced in nextTime/dueAfterMs. That is the accepted cost of not restructuring the view layer in this slice; a later card can collapse the route onto the helper if it is ever worth the diff.

Decision record

The PR ships docs/decisions/0017-one-next-run-decision-three-surfaces.md. main at aa83dc0b holds 16 records with 0015 the highest, but 0016 is already claimed by the #702 branch (docs/decisions/0016-null-currency-is-usd.md, pushing at the lift), so this slice takes 0017. The practice is live, not history: three records each shipped in the same diff as the fix they describe — 0013-settings-retention.md in a7e78981, 0015-job-summary-redaction.md in 318e6101, 0006-standing-check-repair.md in c6939e68 (each verified by the decision file appearing in that commit's own file list). No script or test references docs/decisions/, so nothing enforces it — the convention is the practice, which is why this card names the file instead of leaving it to taste.

Shape, following 0013 (62 lines) and 0015 (71 lines):

• # 0017 — one next-run decision, three surfaces
• Status: **accepted** (<merge date>), Date: <merge date>, Supersedes: nothing; it applies the one-next-run rule (10ea236, stated at docs/architecture.md:107–:113) to the third surface
• ## Context — the three surfaces; the page and the dashboard already answer through one renderer (10ea236622 established the rule, f859f242 extended it to a saved schedule row); the digest still computes last + min(interval, cooldown) at src/jobs/service.ts:2461; docs/architecture.md:107–:113 names only two.
• ## Decision — the helper and its own union, the two branches and what each delegates to, and that the digest owns only its Chinese wording.
• ## Rejected — keeping the formula in the digest; widening NextRunState, which would drag nextRunLine's exhaustive switch into the change.
• ## Consequences — the row-vs-interval choice now lives twice (the accepted cost above); src/jobs stays a caller, never an owner, of the rule.

Acceptance

• For a repository with a cron schedule row, the digest's line carries the planner's instant (nextTime), and the string the interval rule would produce is absent.
• For a repository with auto_iterate = 1, enabled = 0 and no schedule row, the digest says the repository is disabled and prints no instant.
• For a repository with a schedule row and enabled = 0, the digest prints the same planner instant the page prints — enabled is never consulted before a saved row, on either surface.
• For a repository with no schedule row the instant does not change (the floor cannot move it — normalizeInterval clamps interval_minutes to at least 15, src/lib/intervals.ts:13, and the cooldown is clamped at src/config.ts:333 — but the digest must not keep an inline copy of the formula the page gets from dueAfterMs). What does change, and is the point of the table: a no-row repository whose state already has a page sentence — disabled, not-ready, idle, active-job, waiting-first-run — prints that sentence instead of a formatted time, so the email and the page agree on the state as well as the instant.
• The digest's other sections, the page, the dashboard, nextRunLine/plannedNextLine and listRepos are byte-identical in behaviour.
• docs/architecture.md:107–:113 names the daily digest as a third surface of the one next-run rule, so the doc lists every surface that must agree. Doc change in the same PR (src/views//src/jobs/ → docs/architecture.md).
• docs/decisions/0017-…md is in the same diff; the ADR records the decision, the architecture doc names the third surface.
• A changelog fragment ships in the same diff — changelog.d/<issue>.fixed.md, one paragraph, no heading, no leading - — because the digest's 明天 line is user-visible. Both precedent commits did this: changelog.d/564-one-next-run.fixed.md in 10ea236622 and changelog.d/688.fixed.md in f859f242; both have since been consumed by the release that followed, which is the normal lifecycle of a fragment, not a reason to skip it.

Non-goals

• Not moving nextRunLine/plannedNextLine out of src/views/pages.ts, and not changing the route's ScheduledNext contract.
• Not adding an enabled filter to listRepos (src/db.ts:4122): a disabled repository still belongs in the digest's job history and spend.
• Not making the digest bilingual. The email is Chinese-only today; translating it is a separate decision.
• Not touching the rest of buildDigest (jobs, spend, questions, team links) or the digest_sent:<userId>:<date> bookkeeping (src/jobs/service.ts:2507–:2509).
• Not modelling scheduler leases or misfire policy in the email; "runs next" means the same thing it means on the page.

Evidence

• Live main at filing: aa83dc0b407fb1d9da116663ec4b199734c25ba8 ("release: v0.3.6 (release: v0.3.6 #712)"), read from the GitHub API. Every file:line above was re-read at that sha; the only commit between the audit and filing is the v0.3.6 release, which touches CHANGELOG.md, README*, changelog.d/, package*.json and docker-compose.yml and no src/, docs/ or .github/agent/ file. docs/decisions/ on main still holds 16 records with 0015 the highest; 0016 is claimed by the bug: an upgraded instance shows two USD rows in the cost-by-currency table #702 branch, so 0017 is the next free number.
• risk-tier: T3 — .github/agent/risk-rules.json:31 lists src/jobs/** under T3 and the tier is computed from the diff, so the buildDigest call-site change alone is T3 whatever home the helper gets. The docs/decisions/0017 file is T0 and does not move it.
• Dedupe: two closed issues cover the other two surfaces — feat: show one next-run time on the dashboard and the repository page, computed by one function #564 ("show one next-run time on the dashboard and the repository page, computed by one function") and bug: the dashboard's next-run card ignores a repository schedule and disagrees with the schedule console #688 ("the dashboard's next-run card ignores a repository schedule"). The bug: the dashboard's next-run card ignores a repository schedule and disagrees with the schedule console #688 fix landed as PR fix(views): the dashboard next-run card answers from a repository schedule (#688) #711 (f859f242a613034b63ae06dfa69167637bd0facd, merged 2026-11-14T11:15:35Z) and its body never mentions the digest; no open PR touches buildDigest (two of the eight edit src/jobs/service.ts elsewhere, neither touches a digest-named line). Branch from live main at the time of work: if either of those lands first, expect at most one conflict in src/jobs/service.ts, resolve it by keeping both sides, and never edit those PRs' hunks or files to make the conflict go away; no open or closed issue reports this line — the open cards whose text mentions "digest" are image-digest pinning (security: pin container base images by digest #647) and unrelated feature work (feat: make scheduled carry-over evidence-linked and falsification-gated #365, feat: make scheduled runs first-class occurrences with timezone, misfire and layered budgets #544, feat: make only action-needed events interrupt the maintainer #633, bug: the asset URLs carry no version, so a four-hour cache can serve new HTML against the old stylesheet #700, feat: make a job replayable from its tool calls, context hashes and model decisions #383, feat: purge trial-expired accounts inside the trial sweep #690, feat: add agent-written project memory and repository document promotion #638). test/digestEmail.test.ts asserts the template only — see "Untested" above.

Labels

Triaged by the Lead: bug, area:ui, area:jobs. The Reviewer's first pass returned Issue-review: CHANGES; this revision answers its three blocking points — case 2 is split into the no-row and the with-row fixtures, the fixture now states auto_iterate = 1, enabled = 0 explicitly, and the instanceImage === '' fallback is in the helper's input contract with its own unit case — and narrows Acceptance to match. review:changes/needs-review stay until the next verdict. Not self-test — this was found by reading the code at aa83dc0b, not by using the platform in a self-test session.

Priority

normal — one line in a daily email; nothing is corrupted and no state is wrong, so it goes out behind the owner-planned and security work at the lift.