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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13406-a-maintenance-duty-that-has-not-run-in-t → main 7 commits fork 1 thread · 1 unresolved

  • Merged. scout/13406-a-maintenance-duty-that-has-not-run-in-t was merged into main as 6eb61b0.

Review

Sign in to review this change.
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
2121 - **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.
2222
2323 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 /**

Add the docs/features/maintenance-duties.md section for duty-idle (see body); the header comment is not a how-to.

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 */
25
36 import type { Database } from "bun:sqlite";
47 import { clip } from "./duty.ts";
@@ -41,7 +44,10 @@ function put(db: Database, name: string, paused: boolean, reason: string, by: st
4144 export const setPaused = (db: Database, name: string, paused: boolean, by: string, now = new Date()): void =>
4245 put(db, name, paused, paused ? `paused by ${by}` : "", by, now);
4346
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 */
4551 export function pauseOnErrors(db: Database, name: string, now = new Date()): boolean {
4652 const from = stateRow(db, name)?.from_run ?? 0;
4753 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
5460 * Three errored runs in a row and no success since. A success (or a resume) clears it.
5561 * `since` is when the streak began; `line` is the latest error's first line.
5662 */
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;
5965 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 }[];
6066 let n = 0;
6167 while (n < rows.length && errored(rows[n]!.outcome)) n++;
@@ -67,14 +73,14 @@ export function failing(db: Database, name: string): { since: string; line: stri
6773 export function dutyState(db: Database, name: string): DutyState {
6874 const s = stateRow(db, name);
6975 if (s?.paused === 1) {
70 const f = failing(db, name);
76 const f = failing(db, name, s.from_run);
7177 // The runner's own pause reason already carries the last error: add only the time.
7278 const more = f === undefined ? "" : s.by === "the runner" ? `; failing since ${f.since}` : `; failing since ${f.since}: ${f.line}`;
7379 const detail = `paused since ${s.since.slice(0, 16).replace("T", " ")} UTC; ${s.reason}${more}`;
7480 return { name, paused: true, says: `${name}: ${detail}.`, detail };
7581 }
7682 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);
7884 const detail = f ? `on; failing since ${f.since}: ${f.line}` : `on${last && errored(last.outcome) ? `; last run errored: ${last.outcome}` : ""}`;
7985 return { name, paused: false, says: `${name}: ${detail}.`, detail };
8086 }
src/maintain/registry.ts +5 −1
@@ -11,5 +11,9 @@ import { duty as v1Proven } from "./duties/v1_proven.ts";
1111 import { duty as backupAge } from "./duties/backup_age.ts";
1212 import { duty as mergedBranches } from "./duties/merged_branches.ts";
1313 import { duty as diskFree } from "./duties/disk_free.ts";
14 import { dutyIdle } from "./duties/duty_idle.ts";
1415
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs