Public: anyone can read this; the crew can change it.
A maintenance duty that has not run in twice its interval raises one issue naming the duty #13437
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13406-a-maintenance-duty-that-has-not-run-in-t → main 7 commits fork 1 thread · 1 unresolved
5 files
changed +125
−7
docs/features/maintenance-duties.md +10
| @@ -21,3 +21,13 @@ The `merged-branches` duty finds branches of pulls that merged over seven days a | ||
| 21 | 21 | - **In the terminal.** Ctrl-K, **Branches of pulls merged over 7 days ago**: the same rows; `d` deletes them all after a confirm, with the same receipt. |
| 22 | 22 | |
| 23 | 23 | Tests: `test/maintain-merged-branches.test.ts`, `test/maintain-merged-web.test.ts`. |
| 24 | ||
| 25 | ## Duty idle (#13406) | |
| 26 | ||
| 27 | The `duty-idle` duty watches the other duties for silence. Hourly, it looks at when each duty last started (budget stops do not count as a start). A duty whose last start is more than twice its interval ago is idle; exactly 2x is not. A duty that has never run is skipped, because there is no last run to name. The watcher never watches itself. | |
| 28 | ||
| 29 | For each idle duty it files one issue, once (an open one is not filed again), titled `The maintenance duty <name> has not run in twice its interval`. The body gives the last run time and the interval. It spends no money. | |
| 30 | ||
| 31 | There is no terminal screen for it: it files an issue, and both doors (the web and the terminal) already show issues. | |
| 32 | ||
| 33 | Tests: `test/duty-idle.test.ts`. |
src/maintain/duties/duty_idle.ts added +51
| @@ -0,0 +1,51 @@ | ||
| 1 | /** | |
| 2 | * Duty idle (#13406): a duty whose last run is older than twice its interval | |
| 3 | * files one defect naming it and when it last ran. A silent crew is a failure | |
| 4 | * the board cannot show. The watcher is exempt from its own watch (it would | |
| 5 | * report itself, or loop), and a duty that has never run has no last run to name. | |
| 6 | */ | |
| 7 | ||
| 8 | import { fileIssueOnce } from "../../checks/flake.ts"; | |
| 9 | import { getRepo } from "../../core/repos.ts"; | |
| 10 | import { ownRepoPath } from "../../kernel/own_repo.ts"; | |
| 11 | import type { Duty } from "../duty.ts"; | |
| 12 | import { lastStarted } from "../runs.ts"; | |
| 13 | ||
| 14 | export const NAME = "duty-idle"; | |
| 15 | export const titleOf = (duty: string): string => `The maintenance duty ${duty} has not run in twice its interval`; | |
| 16 | ||
| 17 | /** The watcher over these duties; it never watches itself. */ | |
| 18 | export function dutyIdle(watched: readonly Duty[]): Duty { | |
| 19 | return { | |
| 20 | name: NAME, | |
| 21 | intervalMs: 3_600_000, | |
| 22 | budget: { runsPerDay: 30, dollarsPerDay: 0, reason: "hourly is 24 a day; the rest is room for a catch-up, and it spends no money" }, | |
| 23 | run({ db, bus, now }) { | |
| 24 | const findings = []; | |
| 25 | const actions: string[] = []; | |
| 26 | const [owner = "", name = ""] = ownRepoPath().split("/"); | |
| 27 | const repo = getRepo(db, owner, name); | |
| 28 | for (const d of watched) { | |
| 29 | if (d.name === NAME) continue; | |
| 30 | const last = lastStarted(db, d.name); | |
| 31 | if (last === undefined || now.getTime() - last <= 2 * d.intervalMs) continue; | |
| 32 | const lastAt = new Date(last).toISOString(); | |
| 33 | const idleMs = now.getTime() - last; | |
| 34 | findings.push({ | |
| 35 | summary: `${d.name} last ran ${lastAt}, over twice its interval of ${Math.round(d.intervalMs / 60_000)} min`, | |
| 36 | probe: { kind: "query" as const, what: `ms since ${d.name} last started`, number: idleMs, at: now.toISOString() }, | |
| 37 | }); | |
| 38 | if (repo === undefined) continue; | |
| 39 | const filed = fileIssueOnce(db, bus, repo, { | |
| 40 | title: titleOf(d.name), | |
| 41 | body: | |
| 42 | `_Filed by the duty idle watcher from the maintenance record, not written by a person._\n\n` + | |
| 43 | `\`${d.name}\` last ran at ${lastAt}, ${Math.round(idleMs / 60_000)} min ago; its interval is ${Math.round(d.intervalMs / 60_000)} min. ` + | |
| 44 | `Find why it stopped: a crash, a budget, a pause, or a stuck run.`, | |
| 45 | }); | |
| 46 | if (filed.opened) actions.push(`filed idle issue #${filed.number} for ${d.name}`); | |
| 47 | } | |
| 48 | return { findings, actions }; | |
| 49 | }, | |
| 50 | }; | |
| 51 | } |
src/maintain/pause.ts +12 −6
| @@ -1,4 +1,7 @@ | ||
| 1 | /** A maintenance duty's on/off switch (#11205): stored, set by a person or by three errors in a row; plain data in and out. */ | |
| 1 | /** | |
| 2 | * A maintenance duty's on/off switch (#11205): stored, set by a person or by three errors in a row; | |
| 3 | * plain data in and out. | |
| 4 | */ | |
| 2 | 5 | |
| 3 | 6 | import type { Database } from "bun:sqlite"; |
| 4 | 7 | import { clip } from "./duty.ts"; |
| @@ -41,7 +44,10 @@ function put(db: Database, name: string, paused: boolean, reason: string, by: st | ||
| 41 | 44 | export const setPaused = (db: Database, name: string, paused: boolean, by: string, now = new Date()): void => |
| 42 | 45 | put(db, name, paused, paused ? `paused by ${by}` : "", by, now); |
| 43 | 46 | |
| 44 | /** After a run: three errored runs in a row (since the last resume) pause the duty, with the last error as the reason. Returns whether it paused. */ | |
| 47 | /** | |
| 48 | * After a run: three errored runs in a row (since the last resume) pause the duty, with the last | |
| 49 | * error as the reason. Returns whether it paused. | |
| 50 | */ | |
| 45 | 51 | export function pauseOnErrors(db: Database, name: string, now = new Date()): boolean { |
| 46 | 52 | const from = stateRow(db, name)?.from_run ?? 0; |
| 47 | 53 | const rows = db.query("SELECT outcome FROM maintenance_run WHERE duty = ?1 AND id > ?2 AND outcome NOT LIKE 'budget:%' ORDER BY id DESC LIMIT ?3").all(name, from, ERRORS_TO_PAUSE) as { outcome: string }[]; |
| @@ -54,8 +60,8 @@ export function pauseOnErrors(db: Database, name: string, now = new Date()): boo | ||
| 54 | 60 | * Three errored runs in a row and no success since. A success (or a resume) clears it. |
| 55 | 61 | * `since` is when the streak began; `line` is the latest error's first line. |
| 56 | 62 | */ |
| 57 | export function failing(db: Database, name: string): { since: string; line: string } | undefined { | |
| 58 | const from = stateRow(db, name)?.from_run ?? 0; | |
| 63 | export function failing(db: Database, name: string, fromRun?: number): { since: string; line: string } | undefined { | |
| 64 | const from = fromRun ?? stateRow(db, name)?.from_run ?? 0; | |
| 59 | 65 | const rows = db.query("SELECT started, outcome FROM maintenance_run WHERE duty = ?1 AND id > ?2 AND outcome NOT LIKE 'budget:%' ORDER BY id DESC").all(name, from) as { started: string; outcome: string }[]; |
| 60 | 66 | let n = 0; |
| 61 | 67 | while (n < rows.length && errored(rows[n]!.outcome)) n++; |
| @@ -67,14 +73,14 @@ export function failing(db: Database, name: string): { since: string; line: stri | ||
| 67 | 73 | export function dutyState(db: Database, name: string): DutyState { |
| 68 | 74 | const s = stateRow(db, name); |
| 69 | 75 | if (s?.paused === 1) { |
| 70 | const f = failing(db, name); | |
| 76 | const f = failing(db, name, s.from_run); | |
| 71 | 77 | // The runner's own pause reason already carries the last error: add only the time. |
| 72 | 78 | const more = f === undefined ? "" : s.by === "the runner" ? `; failing since ${f.since}` : `; failing since ${f.since}: ${f.line}`; |
| 73 | 79 | const detail = `paused since ${s.since.slice(0, 16).replace("T", " ")} UTC; ${s.reason}${more}`; |
| 74 | 80 | return { name, paused: true, says: `${name}: ${detail}.`, detail }; |
| 75 | 81 | } |
| 76 | 82 | const last = db.query("SELECT outcome FROM maintenance_run WHERE duty = ?1 ORDER BY id DESC LIMIT 1").get(name) as { outcome: string } | null; |
| 77 | const f = failing(db, name); | |
| 83 | const f = failing(db, name, s?.from_run ?? 0); | |
| 78 | 84 | const detail = f ? `on; failing since ${f.since}: ${f.line}` : `on${last && errored(last.outcome) ? `; last run errored: ${last.outcome}` : ""}`; |
| 79 | 85 | return { name, paused: false, says: `${name}: ${detail}.`, detail }; |
| 80 | 86 | } |
src/maintain/registry.ts +5 −1
| @@ -11,5 +11,9 @@ import { duty as v1Proven } from "./duties/v1_proven.ts"; | ||
| 11 | 11 | import { duty as backupAge } from "./duties/backup_age.ts"; |
| 12 | 12 | import { duty as mergedBranches } from "./duties/merged_branches.ts"; |
| 13 | 13 | import { duty as diskFree } from "./duties/disk_free.ts"; |
| 14 | import { dutyIdle } from "./duties/duty_idle.ts"; | |
| 14 | 15 | |
| 15 | export const duties: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention, backupGrowth, backupAge, v1Proven, diskFree, mergedBranches]; | |
| 16 | const others: readonly Duty[] = [pullsWaiting, ruleWatcher, efficiencyWatcher, flowKeeper, visitorRetention, backupGrowth, backupAge, v1Proven, diskFree, mergedBranches]; | |
| 17 | ||
| 18 | /** The duties plus the one that watches them for silence. */ | |
| 19 | export const duties: readonly Duty[] = [...others, dutyIdle(others)]; |
test/duty-idle.test.ts added +47
| @@ -0,0 +1,47 @@ | ||
| 1 | /** | |
| 2 | * Duty idle (#13406): a duty silent for over twice its interval files one defect; the watcher is | |
| 3 | * exempt. | |
| 4 | */ | |
| 5 | import { expect, test } from "bun:test"; | |
| 6 | import { dutyIdle, NAME, titleOf } from "../src/maintain/duties/duty_idle.ts"; | |
| 7 | import type { Duty } from "../src/maintain/duty.ts"; | |
| 8 | import { duties } from "../src/maintain/registry.ts"; | |
| 9 | import { record } from "../src/maintain/runs.ts"; | |
| 10 | import { rulesWorld } from "./helpers/rules-app.ts"; | |
| 11 | ||
| 12 | process.env.FORGE_SENTINEL_REPO = "alice/rules"; | |
| 13 | const w = rulesWorld(); | |
| 14 | const MIN = 60_000; | |
| 15 | const T0 = Date.parse("2026-11-01T00:00:00Z"); | |
| 16 | const quiet: Duty = { name: "quiet-one", intervalMs: 10 * MIN, budget: { runsPerDay: 1, dollarsPerDay: 0, reason: "t" }, run: () => ({ findings: [], actions: [] }) }; | |
| 17 | const watcher = dutyIdle([quiet, dutyIdle([])]); | |
| 18 | const ran = (at: number) => record(w.app.db, { duty: quiet.name, started: new Date(at), finished: new Date(at), findings: [], actions: [], outcome: "ok" }); | |
| 19 | const run = (at: number) => watcher.run({ db: w.app.db, bus: w.app.bus, now: new Date(at) }); | |
| 20 | const defects = () => w.titles().filter((t) => t === titleOf("quiet-one")); | |
| 21 | ||
| 22 | test("registered, and a duty that never ran or ran recently files nothing", async () => { | |
| 23 | expect(duties.map((d) => d.name)).toContain(NAME); | |
| 24 | expect((await run(T0)).actions).toEqual([]); | |
| 25 | ran(T0); | |
| 26 | expect((await run(T0 + 20 * MIN)).actions).toEqual([]); // exactly twice: not over | |
| 27 | expect(defects()).toHaveLength(0); | |
| 28 | }); | |
| 29 | ||
| 30 | test("over twice the interval files one defect naming the duty and its last run, once while open", async () => { | |
| 31 | const r = await run(T0 + 21 * MIN); | |
| 32 | expect(r.actions).toHaveLength(1); | |
| 33 | expect(r.findings).toHaveLength(1); | |
| 34 | const body = w.app.db.query<{ body: string }, [string]>("SELECT body FROM issue WHERE title = ?1").get(titleOf("quiet-one"))!.body; | |
| 35 | expect(body).toContain("quiet-one"); | |
| 36 | expect(body).toContain("2026-11-01T00:00:00.000Z"); | |
| 37 | expect((await run(T0 + 90 * MIN)).actions).toEqual([]); | |
| 38 | expect(defects()).toHaveLength(1); | |
| 39 | }); | |
| 40 | ||
| 41 | test("the watcher is exempt: it never files about itself", async () => { | |
| 42 | const self = dutyIdle([dutyIdle([])]); | |
| 43 | record(w.app.db, { duty: NAME, started: new Date(T0), finished: new Date(T0), findings: [], actions: [], outcome: "ok" }); | |
| 44 | const r = await self.run({ db: w.app.db, bus: w.app.bus, now: new Date(T0 + 99 * 60 * MIN) }); | |
| 45 | expect(r.findings).toEqual([]); | |
| 46 | expect(w.titles().filter((t) => t === titleOf(NAME))).toHaveLength(0); | |
| 47 | }); |
new above
offline
Add the docs/features/maintenance-duties.md section for duty-idle (see body); the header comment is not a how-to.