Public: anyone can read this; the crew can change it.

Maintenance framework: a maintainer crew role with scheduled duties, budgets and probe-backed findings #8933

Parked opened this in answer to
Closed without merging

mason/forge:mason/7554-maintenance-framework-a-maintainer-crew → main 8 commits fork 3 threads · 3 unresolved

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
41 files changed +1592 −4
docs/design/audit.md +1
@@ -60,6 +60,7 @@ Machine routes are not pages and have no entry: `/audit.csv`,
6060 - `/asked` — `studio/asked_page.ts` · what I answered, as a record · `/asks` · none seen.
6161 - `/review` — `studio/review_page.ts` · every ask waiting on me, one row each, newest first · `/asks` (same asks, with buttons) · none seen.
6262 - `/flow` — `pages/flow.ts` · the pipeline from ready issue to live deploy, and the bottleneck · `/system`, `/board`, `/` · none seen. A topbar button points here.
63 - `/maintain` — `pages/maintain.ts` · the maintainer's duties and latest runs, a forge admin's; Pause and Resume are post forms · `/flow` (a Maintainer button), the terminal's Maintainer entry · none seen.
6364 - `/talk` — `pages/talk.ts` · the person's one conversation with the forge: history, composer, Confirm and Cancel; replies stream in over `/talk/stream` · `/settings/confirms` (the same yes, as a list), the home tell box (one line to an app's crew) · none seen; styles in `docs/design/areas/talk.md`.
6465 - `/notes` — `pages/notes.ts` · what the person wrote, newest first, with the planner's verdict and live state in one line, and one tap to overrule it · the home tell box (Notes button), the user menu, the palette · none seen; styles in `docs/design/areas/notes.md`.
6566 - `/pipeline` — `pages/pipeline.ts` · the four steps a change follows (check, review, land, live), for a newcomer · a pull page's step line, `/flow` · none seen.
docs/features/maintainer.md added +32
@@ -0,0 +1,32 @@
1 # The maintainer (#7554)
2
3 A crew role (`maintainer`) for scheduled duties. A duty is a name, a trigger
4 (`{ every: ms }`; an event trigger comes when something emits events), a budget (runs a day, dollars a day,
5 milliseconds and network calls a run), a switch and a handler returning
6 findings and actions.
7
8 - **Add a duty:** one file in `src/maintain/duties/` using `duty({...})`, one
9 import and one entry in `duties/index.ts`. `run_log.ts` is the pattern.
10 - **Probes:** every finding and action carries `ctx.probe(query, value)`; the
11 runner drops one without it and records the run as `refused`.
12 - **Findings** go to the open issue for their stable key as a comment, or open
13 one (`maintain/file.ts`, table `maintenance_finding`), as the seated
14 `maintainer` agent; with none seated nothing is filed. A repeat comments
15 only when the evidence changed or a day has passed. A run admits at most 20
16 findings, titles of 200 characters, evidence of 20 lines of 500.
17 - **Bulk:** `ctx.bulk(items, { apply, check })` applies one item, checks its
18 probe, then continues, capped at 20 a run; a failed check records `canary`.
19 - **Budget:** over a day's runs or dollars, or past a run's network ceiling,
20 the outcome is `budget`. A handler still going at its time ceiling is
21 abandoned (its late calls throw) and the run is `budget`.
22 - **Errors:** three in a row pause the duty with the reason.
23 - **No landing:** a duty is handed `now`, `probe`, `net`, `spend`, `bulk` and
24 `runs` (its own run log), never a database handle, and its files import
25 nothing but `../duty.ts`; `src/maintain/` imports nothing that merges,
26 pushes or spawns (`test/maintain-no-land.test.ts`). Fixes are pulls.
27 - **Doors, all a forge admin's:** `/maintain` (links, post forms to pause or
28 resume), the "Maintainer" palette entry in the terminal (`p` toggles), and
29 `GET /api/v1/maintain/duties`, `GET …/runs?duty=`,
30 `POST …/duties/:name/pause|resume` (forge admin).
31
32 Starts on the autonomy clock after the sentinel but detached (`maintainInBackground`), so a slow duty never holds the sentinel, triage or review.
src/contract/openapi/routes/getApiV1MaintainDuties.ts added +10
@@ -0,0 +1,10 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "get",
5 path: "/api/v1/maintain/duties",
6 summary:
7 "The maintainer's duties with trigger, budget, switch, why one is paused and its last run (a person admin's token); answers { duties }",
8 auth: true,
9 refusals: { forbidden: "the token is not a person who administers the forge" },
10 };
src/contract/openapi/routes/getApiV1MaintainRuns.ts added +10
@@ -0,0 +1,10 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "get",
5 path: "/api/v1/maintain/runs",
6 summary:
7 "The maintainer's run rows, newest first, each with findings, actions, probes, outcome and cost; ?duty= narrows to one duty (a person admin's token); answers { runs }",
8 auth: true,
9 refusals: { forbidden: "the token is not a person who administers the forge" },
10 };
src/contract/openapi/routes/index.ts +4
@@ -77,6 +77,8 @@ export { route as getApiV1Front } from "./getApiV1Front.ts";
7777 export { route as getApiV1Health } from "./getApiV1Health.ts";
7878 export { route as getApiV1Here } from "./getApiV1Here.ts";
7979 export { route as getApiV1Keeper } from "./getApiV1Keeper.ts";
80 export { route as getApiV1MaintainDuties } from "./getApiV1MaintainDuties.ts";
81 export { route as getApiV1MaintainRuns } from "./getApiV1MaintainRuns.ts";
8082 export { route as getApiV1Map } from "./getApiV1Map.ts";
8183 export { route as getApiV1MigrateJob } from "./getApiV1MigrateJob.ts";
8284 export { route as getApiV1MigrateJobStream } from "./getApiV1MigrateJobStream.ts";
@@ -234,6 +236,8 @@ export { route as postApiV1FleetOpsIdUndo } from "./postApiV1FleetOpsIdUndo.ts";
234236 export { route as postApiV1Forges } from "./postApiV1Forges.ts";
235237 export { route as postApiV1ForgesNameClaimLink } from "./postApiV1ForgesNameClaimLink.ts";
236238 export { route as postApiV1Heartbeat } from "./postApiV1Heartbeat.ts";
239 export { route as postApiV1MaintainDutiesNamePause } from "./postApiV1MaintainDutiesNamePause.ts";
240 export { route as postApiV1MaintainDutiesNameResume } from "./postApiV1MaintainDutiesNameResume.ts";
237241 export { route as postApiV1Migrate } from "./postApiV1Migrate.ts";
238242 export { route as postApiV1Orgs } from "./postApiV1Orgs.ts";
239243 export { route as postApiV1OrgsOrgTeams } from "./postApiV1OrgsOrgTeams.ts";
src/contract/openapi/routes/postApiV1MaintainDutiesNamePause.ts added +10
@@ -0,0 +1,10 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "post",
5 path: "/api/v1/maintain/duties/{name}/pause",
6 summary:
7 "Pause a maintainer duty until it is resumed (admin scope); answers { duties }",
8 auth: true,
9 refusals: { forbidden: "the token is not a person who administers the forge" },
10 };
src/contract/openapi/routes/postApiV1MaintainDutiesNameResume.ts added +10
@@ -0,0 +1,10 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "post",
5 path: "/api/v1/maintain/duties/{name}/resume",
6 summary:
7 "Resume a paused maintainer duty and clear its error count (admin scope); answers { duties }",
8 auth: true,
9 refusals: { forbidden: "the token is not a person who administers the forge" },
10 };
src/core/agents.ts +5 −3
@@ -303,14 +303,16 @@ export function deleteAgent(db: Database, userId: string): boolean {
303303 /**
304304 * What a crew member is for on one repository: a builder takes what is
305305 * ready, a planner turns a direction into a map, a reviewer looks at what
306 * landed. Per repository, because the same agent may plan one and build
307 * another.
306 * landed, a maintainer runs scheduled duties (`src/maintain/`) and proposes
307 * only through pulls. Per repository, because the same agent may plan one
308 * and build another.
308309 */
309 export type CrewRole = "builder" | "planner" | "reviewer";
310 export type CrewRole = "builder" | "planner" | "reviewer" | "maintainer";
310311 export const CREW_ROLES: readonly CrewRole[] = [
311312 "planner",
312313 "builder",
313314 "reviewer",
315 "maintainer",
314316 ];
315317 export const isCrewRole = (value: unknown): value is CrewRole =>
316318 (CREW_ROLES as readonly unknown[]).includes(value);
src/core/migration-pins/20261103150000-maintenance.pin added +1
@@ -0,0 +1,1 @@
1 bcb4fbf97a17f8b60ac4173cf297d0acea8f9e2f0bf1262e4eea092098e8cbaf
src/core/migrations/20261103150000-maintenance.ts added +32
@@ -0,0 +1,32 @@
1 // The maintainer's duties (#7554): which duties are paused and why, one row
2 // per run with the findings, actions and probes it left, and the issue a
3 // finding's stable key was filed to, when it was last said and with what
4 // evidence. Additive.
5 export default `
6 CREATE TABLE maintenance_duty (
7 name TEXT PRIMARY KEY,
8 enabled INTEGER NOT NULL DEFAULT 1,
9 paused_reason TEXT,
10 errors INTEGER NOT NULL DEFAULT 0
11 ) WITHOUT ROWID;
12 CREATE TABLE maintenance_run (
13 id TEXT PRIMARY KEY,
14 duty TEXT NOT NULL,
15 started TEXT NOT NULL,
16 finished TEXT NOT NULL,
17 findings TEXT NOT NULL,
18 actions TEXT NOT NULL,
19 probes TEXT NOT NULL,
20 outcome TEXT NOT NULL,
21 cost REAL NOT NULL DEFAULT 0,
22 detail TEXT
23 ) WITHOUT ROWID;
24 CREATE INDEX maintenance_run_duty ON maintenance_run(duty, started);
25 CREATE TABLE maintenance_finding (
26 key TEXT PRIMARY KEY,
27 issue_id TEXT NOT NULL,
28 first_seen TEXT NOT NULL,
29 last_seen TEXT NOT NULL,
30 evidence TEXT NOT NULL DEFAULT ''
31 ) WITHOUT ROWID;
32 `;
src/core/reserved.ts +1
@@ -57,6 +57,7 @@ export const SYSTEM_NAMES: readonly string[] = [
5757 // the forge's own pages
5858 "api",
5959 "apps",
60 "maintain",
6061 "asks",
6162 "assets",
6263 "audit",
src/crew/autonomy.ts +4
@@ -64,6 +64,7 @@ import { getHold } from "../core/holds.ts";
6464 import { certain } from "./decide.ts";
6565 import { decideAndRecord } from "./ledger.ts";
6666 import { sentinelTick } from "./sentinel.ts";
67 import { maintainInBackground } from "../maintain/service.ts";
6768 import { triageTick } from "./triage.ts";
6869 import { liveTriage, none as noTriage, tickFields } from "./livetriage.ts";
6970 import { wallOf, wallPlain, wallSentence } from "../contract/policy.ts";
@@ -1463,6 +1464,9 @@ export async function autonomyTick(
14631464 log.error("sentinel failed", { error: String(error) });
14641465 }
14651466 await breathe();
1467 // The maintainer's duties that are due (`maintain/runner.ts`).
1468 maintainInBackground(app, now.getTime(), (error) => log.error("maintainer failed", { error: String(error) }));
1469 await breathe();
outdated

HIGH: this await runs duty code inline in the autonomy tick with no hard deadline; a hung duty stops the sentinel, triage and review behind it. Give it a deadline or run it detached with its own guard.

14661470 // Review is not autonomy's alone: an agent's green pull is read by the
14671471 // crew's reviewer in every repository that has one.
14681472 try {
src/crew/seat_slots.ts +1
@@ -34,6 +34,7 @@ export const SEAT_UNIT: Record<CrewRole, string> = {
3434 planner: "planning pass at once",
3535 builder: "build at once",
3636 reviewer: "review at once",
37 maintainer: "duty at once",
3738 };
3839
3940 export function slotsOf(repo: Repo, role: CrewRole): number {
src/http/api.ts +2
@@ -333,6 +333,7 @@ import { visionRoutes } from "./api/vision.ts";
333333 import { tokenRoutes } from "./api/tokens.ts";
334334 import { accountAdmin, adminRoutes } from "./api/admin.ts";
335335 import { flagsRoutes } from "./api/flags.ts";
336 import { maintainRoutes } from "./api/maintain.ts";
336337 import { issueRoutes, labelsHandler } from "./api/issues.ts";
337338 import { FORGE_NOT_CARRIED } from "../origins/words.ts";
338339 import { forgeOriginRoutes } from "./api/forge_origin.ts";
@@ -1166,6 +1167,7 @@ export function apiRoutes(router: Router<Handler>): void {
11661167 forgeOriginRoutes(router);
11671168 adminRoutes(router);
11681169 flagsRoutes(router);
1170 maintainRoutes(router);
11691171
11701172 // Open read hooks (#1789): the owner, or an agent holding `telemetry:read`.
11711173 // Anyone else is refused; every agent read is logged.
src/http/api/maintain.ts added +35
@@ -0,0 +1,35 @@
1 /**
2 * The maintainer's duties over HTTP (#7554): `GET /api/v1/maintain/duties`
3 * with each duty's budget, switch and last run; `GET …/runs` for the run
4 * rows; `POST …/duties/:name/pause` and `/resume`. A forge admin's door.
5 */
6
7 import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
8 import { dutyBoard, dutyRuns, setDutyPaused } from "../../maintain/service.ts";
9 import type { Ctx, Handler } from "../context.ts";
10 import { json, notFound, requireScope } from "../respond.ts";
11 import type { Router } from "../router.ts";
12
13 const door = (ctx: Ctx, scope: "ro" | "admin"): Response | undefined => {
14 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
15 return ctx.auth.user?.isAdmin === true ? requireScope(ctx, scope) : notFound();
16 };
17
18 export function maintainRoutes(router: Router<Handler>): void {
19 router.add("GET", "/api/v1/maintain/duties", (ctx) => door(ctx, "ro") ?? json({ duties: dutyBoard(ctx.app) }));
20 router.add("GET", "/api/v1/maintain/runs", (ctx) => {
21 const denied = door(ctx, "ro");
22 if (denied) return denied;
23 const duty = ctx.url.searchParams.get("duty") ?? undefined;
24 return json({ runs: dutyRuns(ctx.app, duty) });
25 });
26 const switchDuty = (paused: boolean): Handler => (ctx) => {
27 const denied = door(ctx, "admin");
28 if (denied) return denied;
29 return setDutyPaused(ctx.app, ctx.params.name!, paused, ctx.auth.user!.username)
30 ? json({ duties: dutyBoard(ctx.app) })
31 : notFound();
32 };
33 router.add("POST", "/api/v1/maintain/duties/:name/pause", switchDuty(true));
34 router.add("POST", "/api/v1/maintain/duties/:name/resume", switchDuty(false));
35 }
src/http/server.ts +4
@@ -275,6 +275,7 @@ import { appStateFragment } from "../web/studio/previews.ts";
275275 import { changesList, tellsList } from "../web/studio/lists.ts";
276276 import { dependencySubmit } from "../web/pages/thread.ts";
277277 import { flowPage, suggestionTake, valveSet } from "../web/pages/flow.ts";
278 import { maintainPage, switchDuty } from "../web/pages/maintain.ts";
278279 import { heldApply, heldPage, liftHoldSubmit } from "../web/pages/gate.ts";
279280 import {
280281 assigneeSubmit,
@@ -801,6 +802,9 @@ export function buildRouter(): Router<Handler> {
801802 router.add("GET", "/flow", flowPage);
802803 router.add("POST", "/flow/valve", valveSet);
803804 router.add("POST", "/flow/suggestion", suggestionTake);
805 router.add("GET", "/maintain", maintainPage);
806 router.add("POST", "/maintain/duties/:name/pause", switchDuty(true));
807 router.add("POST", "/maintain/duties/:name/resume", switchDuty(false));
804808 router.add("GET", "/system", systemPage);
805809 router.add("GET", "/system/stream", systemStream);
806810 router.add("GET", "/contribute", contributePage);
src/maintain/duties/index.ts added +6
@@ -0,0 +1,6 @@
1 /** Every registered duty: a worker adds its file here and imports it on one line. */
2
3 import type { Duty } from "../duty.ts";
4 import { runLog } from "./run_log.ts";
5
6 export const dutyList: readonly Duty[] = [runLog];
src/maintain/duties/run_log.ts added +30
@@ -0,0 +1,30 @@
1 /**
2 * The maintainer's own housekeeping: `maintenance_run` is read by the board
3 * and grows with every run, so rows past 90 days are pruned, the oldest
4 * first, one first and its probe checked, then the rest.
5 */
6
7 import { DAY_MS, duty } from "../duty.ts";
8
9 const KEEP_DAYS = 90;
10
11 export const runLog = duty({
12 name: "run-log",
13 trigger: { every: DAY_MS },
14 budget: { runsPerDay: 2, usdPerDay: 0, cpuMsPerRun: 10_000, netCallsPerRun: 0 },
15 async handler(ctx) {
16 const before = new Date(ctx.now - KEEP_DAYS * DAY_MS).toISOString();
17 const old = ctx.runs.before(before, 20);
18 if (old.length === 0) return {};
19 await ctx.bulk(old, {
20 what: "prune run",
21 target: (id) => id,
22 apply: (id) => ctx.runs.prune(id),
23 check: (id) => {
24 const left = ctx.runs.has(id) ? 1 : 0;
25 return { ...ctx.probe("SELECT COUNT(*) FROM maintenance_run WHERE id = :pruned", left), pass: left === 0 };
26 },
27 });
28 return {};
29 },
30 });
src/maintain/duty.ts added +106
@@ -0,0 +1,106 @@
1 /**
2 * What a duty is (#7554): a name, a trigger, a budget, a switch and a handler
3 * that returns findings and actions. Plain data in, plain data out; a duty
4 * is given only what `DutyContext` hands it: named accessors, no database
5 * handle, and no way to merge or to push a branch.
6 */
7
8 /** The measurement behind a finding or an action: the query, what it returned, when. */
9 export interface ProbeRecord {
10 readonly query: string;
11 readonly value: number | string | boolean;
12 readonly at: string;
13 }
14
15 export interface FindingInput {
16 /** Stable across runs: the same fault has the same key. */
17 readonly key: string;
18 readonly title: string;
19 readonly evidence: readonly string[];
20 readonly probe: ProbeRecord | undefined;
21 }
22
23 export interface ActionInput {
24 readonly what: string;
25 readonly target: string;
26 readonly probe: ProbeRecord | undefined;
27 }
28
29 export interface Finding extends FindingInput {
30 readonly probe: ProbeRecord;
31 }
32 export interface Action extends ActionInput {
33 readonly probe: ProbeRecord;
34 }
35
36 /** A duty runs on an interval; an event trigger waits until something emits one. */
37 export interface Trigger {
38 readonly every: number;
39 }
40
41 export interface Budget {
42 readonly runsPerDay: number;
43 readonly usdPerDay: number;
44 /** Wall time one run may take; a handler still going then is abandoned and the run is `budget`. */
45 readonly cpuMsPerRun: number;
46 /** Network calls one run may make through `ctx.net()`. */
47 readonly netCallsPerRun: number;
48 }
49
50 export interface BulkStep<T> {
51 readonly what: string;
52 readonly target: (item: T) => string;
53 readonly apply: (item: T) => void | Promise<void>;
54 /** Measured after the first item; the rest run only if `pass`. */
55 readonly check: (item: T) => ProbeRecord & { readonly pass: boolean } | Promise<ProbeRecord & { readonly pass: boolean }>;
56 }
57
58 /** The maintainer's own run log, the one table a duty may touch. */
59 export interface RunLog {
60 /** Ids of runs that started before a moment, oldest first. */
61 before(sinceIso: string, limit: number): string[];
62 prune(id: string): void;
63 has(id: string): boolean;
64 }
65
66 export interface DutyContext {
67 readonly now: number;
68 readonly runs: RunLog;
69 probe(query: string, value: ProbeRecord["value"]): ProbeRecord;
70 /** Count a network call; throws once the run's ceiling is passed. */
71 net(): void;
72 /** Add to the run's dollar cost. */
73 spend(usd: number): void;
74 /** One item first, its probe checked, then the rest, capped. */
75 bulk<T>(items: readonly T[], step: BulkStep<T>): Promise<Action[]>;
76 }
77
78 export interface DutyResult {
79 readonly findings?: readonly FindingInput[];
80 readonly actions?: readonly ActionInput[];
81 }
82
83 export interface Duty {
84 readonly name: string;
85 readonly trigger: Trigger;
86 readonly budget: Budget;
87 readonly enabled: boolean;
88 readonly handler: (ctx: DutyContext) => DutyResult | Promise<DutyResult>;
89 }
90
91 export const BULK_CAP = 20;
92 export const ERRORS_TO_PAUSE = 3;
93 export const DAY_MS = 86_400_000;
94
95 export type Outcome = "ok" | "error" | "budget" | "canary" | "refused";
96
97 /** A duty with the defaults every duty takes. */
98 export function duty(
99 spec: Pick<Duty, "name" | "trigger" | "handler"> & Partial<Pick<Duty, "budget" | "enabled">>,
100 ): Duty {
101 return {
102 enabled: true,
103 budget: { runsPerDay: 24, usdPerDay: 0, cpuMsPerRun: 30_000, netCallsPerRun: 0 },
104 ...spec,
105 };
106 }
src/maintain/file.ts added +55
@@ -0,0 +1,55 @@
1 /**
2 * Where a finding goes (#7554): the open issue for its key gets a comment;
3 * a key with none gets an issue. The same de-duplication the sentinel does,
4 * by a stable key, kept in `maintenance_finding`.
5 */
6
7 import type { App } from "../app.ts";
8 import { addComment, openIssue } from "../actions/issues.ts";
9 import { getAgentByName } from "../core/agents.ts";
10 import { getIssueById } from "../core/issues.ts";
11 import { getRepo } from "../core/repos.ts";
12 import { ownRepoPath } from "../kernel/own_repo.ts";
13 import { DAY_MS, type Finding } from "./duty.ts";
14 import { trackedFinding, trackFinding } from "./store.ts";
15
16 const bodyOf = (f: Finding): string =>
17 [
18 f.title,
19 "",
20 "**Evidence**",
21 ...f.evidence.map((e) => `- ${e}`),
22 "",
23 `**Probe:** \`${f.probe.query}\` returned ${String(f.probe.value)} at ${f.probe.at}`,
24 ].join("\n");
25
26 /** What a finding says, to tell a changed one from a repeated one. */
27 const digest = (f: Finding): string => JSON.stringify([f.evidence, f.probe.value]);
28
29 export function issueFiler(app: App, repoPath = ownRepoPath()): (f: Finding, now: number) => string | undefined {
30 return (f, now) => {
31 const [owner = "", name = ""] = repoPath.split("/");
outdated

MEDIUM: when no maintainer agent exists this files issues and comments as the oldest admin user, so automated text is attributed to a real person. Refuse to file (record the run with detail) when there is no maintainer agent instead of falling back to an admin.

32 const repo = getRepo(app.db, owner, name);
33 // Automated text is the maintainer's, never an admin's: with no maintainer seated, nothing is filed.
34 const maintainer = getAgentByName(app.db, "maintainer");
35 if (maintainer === undefined) throw new Error("no maintainer agent is seated; nothing filed");
36 if (repo === undefined) return undefined;
37 const actor = maintainer.user;
38 const at = new Date(now).toISOString();
39 const evidence = digest(f);
40 const known = trackedFinding(app.db, f.key);
41 const issue = known === undefined ? undefined : getIssueById(app.db, known.issueId);
42 if (known !== undefined && issue !== undefined && issue.state === "open") {
43 // Said again only when it changed or a day has passed.
outdated

MEDIUM: every run of a still-true finding adds another comment. For a duty that runs hourly this is issue spam and unbounded growth. Track last comment time in maintenance_finding and comment at most once a day, or only when the evidence changed.

44 if (known.evidence === evidence && now - Date.parse(known.said) < DAY_MS) return `#${issue.number} (unchanged)`;
45 const said = addComment(app, actor, repo, issue, `Still there at ${at}:\n${f.evidence.map((e) => `- ${e}`).join("\n")}\n\nProbe \`${f.probe.query}\` returned ${String(f.probe.value)}.`);
46 if (!said.ok) throw new Error(`comment: ${String(said.error)}`);
47 trackFinding(app.db, f.key, issue.id, at, evidence);
48 return `#${issue.number} (commented)`;
49 }
50 const made = openIssue(app, actor, repo, { title: f.title, body: bodyOf(f) });
51 if (!made.ok) throw new Error(`file: ${String(made.error)}`);
52 trackFinding(app.db, f.key, made.value.id, at, evidence);
53 return `#${made.value.number}`;
54 };
55 }
src/maintain/probe.ts added +46
@@ -0,0 +1,46 @@
1 /** A finding or an action without the measurement behind it is refused (#7554). */
2
3 import type { Action, ActionInput, Finding, FindingInput, ProbeRecord } from "./duty.ts";
4
5 export function validProbe(p: ProbeRecord | undefined): p is ProbeRecord {
6 return (
7 p !== undefined &&
8 typeof p.query === "string" &&
9 p.query.trim() !== "" &&
10 (typeof p.value === "number" ? Number.isFinite(p.value) : typeof p.value === "string" || typeof p.value === "boolean") &&
11 typeof p.at === "string" &&
12 !Number.isNaN(Date.parse(p.at))
13 );
14 }
15
16 export interface Admitted {
17 readonly findings: Finding[];
18 readonly actions: Action[];
19 /** One line per item refused, and why. */
20 readonly refused: string[];
21 }
22
23 export const MAX_FINDINGS = 20;
24 export const MAX_TITLE = 200;
25 export const MAX_EVIDENCE = 20;
26 export const MAX_EVIDENCE_LINE = 500;
27 export const MAX_ACTIONS = 100;
28
29 export function admit(findings: readonly FindingInput[], actions: readonly ActionInput[]): Admitted {
30 const out: Admitted = { findings: [], actions: [], refused: [] };
31 for (const f of findings) {
32 if (out.findings.length >= MAX_FINDINGS) {
33 out.refused.push(`finding ${f.key}: more than ${MAX_FINDINGS} findings in a run`);
34 } else if (f.title.length > MAX_TITLE || f.evidence.length > MAX_EVIDENCE || f.evidence.some((e) => e.length > MAX_EVIDENCE_LINE)) {
35 out.refused.push(`finding ${f.key}: title over ${MAX_TITLE} characters, or evidence over ${MAX_EVIDENCE} lines of ${MAX_EVIDENCE_LINE}`);
36 } else if (!validProbe(f.probe)) out.refused.push(`finding ${f.key}: no probe`);
37 else if (f.key.trim() === "" || f.title.trim() === "") out.refused.push(`finding ${f.key || "(no key)"}: no key or title`);
38 else out.findings.push({ ...f, probe: f.probe });
39 }
40 for (const a of actions) {
41 if (out.actions.length >= MAX_ACTIONS) out.refused.push(`action ${a.what} ${a.target}: more than ${MAX_ACTIONS} actions in a run`);
42 else if (!validProbe(a.probe)) out.refused.push(`action ${a.what} ${a.target}: no probe`);
43 else out.actions.push({ ...a, probe: a.probe });
44 }
45 return out;
46 }
src/maintain/registry.ts added +21
@@ -0,0 +1,21 @@
1 /** The duty registry (#7554): a worker adds one file in `duties/` and one line to `duties/index.ts`. */
2
3 import type { Duty } from "./duty.ts";
4
5 const NAME = /^[a-z][a-z0-9-]{0,63}$/;
6
7 export function makeRegistry(initial: readonly Duty[] = []) {
8 const byName = new Map<string, Duty>();
9 const add = (d: Duty): void => {
10 if (!NAME.test(d.name)) throw new Error(`duty name ${JSON.stringify(d.name)} is not a lowercase word`);
11 if (byName.has(d.name)) throw new Error(`duty ${d.name} is registered twice`);
12 byName.set(d.name, d);
13 };
14 for (const d of initial) add(d);
15 return {
16 add,
17 get: (name: string): Duty | undefined => byName.get(name),
18 all: (): Duty[] => [...byName.values()],
19 };
20 }
21 export type Registry = ReturnType<typeof makeRegistry>;
src/maintain/runner.ts added +209
@@ -0,0 +1,209 @@
1 /**
2 * The duty runner (#7554): runs the duties that are due, one at a time per
3 * duty, and leaves a `maintenance_run` row for each. A handler that outlives
4 * its `cpuMsPerRun` is abandoned and the run recorded as `budget`. It holds
5 * no way to merge or push: a duty gets named accessors, not the database, and
6 * its fixes are pulls, which the normal gate lands.
7 */
8
9 import type { Database } from "bun:sqlite";
10 import {
11 BULK_CAP,
12 DAY_MS,
13 ERRORS_TO_PAUSE,
14 type Action,
15 type BulkStep,
16 type Duty,
17 type DutyContext,
18 type Finding,
19 type Outcome,
20 type ProbeRecord,
21 } from "./duty.ts";
22 import { admit } from "./probe.ts";
23 import type { Registry } from "./registry.ts";
24 import {
25 dutyState,
26 lastRun,
27 pauseDuty,
28 recordRun,
29 setErrors,
30 usedSince,
31 deleteRun,
32 runExists,
33 runIdsBefore,
34 type RunRow,
35 } from "./store.ts";
36
37 class OverBudget extends Error {}
38
39 /** The handler's answer, or a refusal once its time is up. */
40 function within<T>(ms: number, work: Promise<T>): Promise<T> {
41 let timer: ReturnType<typeof setTimeout> | undefined;
42 const late = new Promise<never>((_, reject) => {
43 timer = setTimeout(() => reject(new OverBudget(`took longer than ${ms} ms`)), ms);
44 });
45 return Promise.race([work, late]).finally(() => clearTimeout(timer));
46 }
47
48 export interface RunnerDeps {
49 readonly db: Database;
50 readonly registry: Registry;
51 /** Files or comments a finding on the issue for its key; returns the issue it is on. */
52 readonly file?: (finding: Finding, now: number) => string | undefined;
53 }
54
55 const iso = (ms: number): string => new Date(ms).toISOString();
56
57 export function makeRunner(deps: RunnerDeps) {
58 const { db } = deps;
59 const running = new Set<string>();
60
61 function due(duty: Duty, now: number): boolean {
62 const last = lastRun(db, duty.name);
63 return last === undefined || now - Date.parse(last.started) >= duty.trigger.every;
64 }
65
66 function overBudget(duty: Duty, now: number): string | undefined {
67 const used = usedSince(db, duty.name, iso(now - DAY_MS));
68 if (used.runs >= duty.budget.runsPerDay) return `${used.runs} runs in the last day, budget ${duty.budget.runsPerDay}`;
69 if (used.usd > duty.budget.usdPerDay) return `$${used.usd.toFixed(2)} in the last day, budget $${duty.budget.usdPerDay}`;
70 return undefined;
71 }
72
73 async function runDuty(duty: Duty, now: number): Promise<RunRow | undefined> {
74 const state = dutyState(db, duty.name);
75 if (!duty.enabled || !state.enabled) return undefined;
76 if (running.has(duty.name)) return undefined;
77 running.add(duty.name);
78 try {
79 return await execute(duty, now);
80 } finally {
81 running.delete(duty.name);
82 }
83 }
84
85 async function execute(duty: Duty, now: number): Promise<RunRow> {
86 const started = iso(now);
87 const row = (p: Partial<RunRow>): RunRow => ({
88 id: crypto.randomUUID(), duty: duty.name, started, finished: iso(Date.now()),
89 findings: [], actions: [], probes: [], outcome: "ok", cost: 0, detail: null, ...p,
90 });
91 const over = overBudget(duty, now);
92 if (over !== undefined) {
93 // Said once per window, not every tick.
94 const last = lastRun(db, duty.name);
95 if (last?.outcome === "budget" && now - Date.parse(last.started) < DAY_MS) return last;
96 const r = row({ outcome: "budget", detail: over });
97 recordRun(db, r);
98 return r;
99 }
100
101 const used = usedSince(db, duty.name, iso(now - DAY_MS));
102 let cost = 0;
103 let calls = 0;
104 let halted: string | undefined;
105 const done: Action[] = [];
106 const probe = (query: string, value: ProbeRecord["value"]): ProbeRecord => ({ query, value, at: iso(Date.now()) });
107 // Once the run has ended, an abandoned handler's late calls do nothing.
108 let ended = false;
109 const live = (): void => {
110 if (ended) throw new OverBudget("the run has ended");
111 };
112 const ctx: DutyContext = {
113 now, probe,
114 runs: {
115 before: (sinceIso, limit) => runIdsBefore(db, sinceIso, limit),
116 prune: (id) => (live(), deleteRun(db, id)),
117 has: (id) => runExists(db, id),
118 },
119 net() {
120 live();
121 if (++calls > duty.budget.netCallsPerRun) throw new OverBudget(`more than ${duty.budget.netCallsPerRun} network calls in a run`);
122 },
123 spend(usd) {
124 live();
125 cost += usd;
126 if (used.usd + cost > duty.budget.usdPerDay) throw new OverBudget(`over $${duty.budget.usdPerDay} a day`);
127 },
128 async bulk<T>(items: readonly T[], step: BulkStep<T>): Promise<Action[]> {
129 const out: Action[] = [];
130 for (const item of items) {
131 if (halted !== undefined || done.length >= BULK_CAP) break;
132 live();
133 await step.apply(item);
134 const seen = await step.check(item);
135 const action: Action = { what: step.what, target: step.target(item), probe: { query: seen.query, value: seen.value, at: seen.at } };
136 out.push(action);
137 done.push(action);
138 if (!seen.pass) halted = `${step.what} ${action.target}: probe ${seen.query} returned ${String(seen.value)}; nothing else touched`;
139 }
140 return out;
141 },
142 };
143
144 let outcome: Outcome = "ok";
145 let detail: string | null = null;
146 let findings: Finding[] = [];
147 let actions: Action[] = [];
148 try {
149 const result = await within(duty.budget.cpuMsPerRun, Promise.resolve().then(() => duty.handler(ctx)));
150 const admitted = admit(result.findings ?? [], result.actions ?? []);
151 findings = admitted.findings;
152 actions = [...done, ...admitted.actions];
153 if (admitted.refused.length > 0) {
154 outcome = "refused";
155 detail = admitted.refused.join("; ");
156 }
157 if (halted !== undefined) {
158 outcome = "canary";
159 detail = halted;
160 }
161 } catch (error) {
162 actions = done;
163 outcome = error instanceof OverBudget ? "budget" : "error";
164 detail = error instanceof Error ? error.message : String(error);
165 } finally {
166 ended = true;
167 }
168
169 const filed: string[] = [];
170 if (outcome !== "error") {
171 for (const f of findings) {
172 try {
173 const ref = deps.file?.(f, now);
174 if (ref !== undefined) filed.push(`${f.key} -> ${ref}`);
175 } catch (error) {
176 detail = `${detail === null ? "" : `${detail}; `}could not file ${f.key}: ${String(error)}`;
177 }
178 }
179 }
180 const r = row({
181 findings, actions, outcome, cost, detail,
182 probes: [...findings.map((f) => f.probe), ...actions.map((a) => a.probe)],
183 });
184 recordRun(db, r);
185
186 if (outcome === "error") {
187 const errors = dutyState(db, duty.name).errors + 1;
188 setErrors(db, duty.name, errors);
189 if (errors >= ERRORS_TO_PAUSE)
190 pauseDuty(db, duty.name, `errored ${errors} times in a row; last: ${detail ?? "unknown"}`);
191 } else if (dutyState(db, duty.name).errors !== 0) setErrors(db, duty.name, 0);
192 return r;
193 }
194
195 return {
196 runDuty,
197 /** Every duty whose interval has passed, each once. */
198 async runDue(now: number): Promise<RunRow[]> {
199 const out: RunRow[] = [];
200 for (const d of deps.registry.all()) {
201 if (!due(d, now)) continue;
202 const r = await runDuty(d, now);
203 if (r !== undefined) out.push(r);
204 }
205 return out;
206 },
207 };
208 }
209 export type Runner = ReturnType<typeof makeRunner>;
src/maintain/service.ts added +61
@@ -0,0 +1,61 @@
1 /** The maintainer wired to the app (#7554): one runner, the default registry, the sentinel's clock. */
2
3 import type { App } from "../app.ts";
4 import { dutyList } from "./duties/index.ts";
5 import { issueFiler } from "./file.ts";
6 import { makeRegistry } from "./registry.ts";
7 import { makeRunner, type Runner } from "./runner.ts";
8 import { dutyState, listRuns, pauseDuty, resumeDuty, lastRun } from "./store.ts";
9
10 const runners = new WeakMap<App, Runner>();
11 const registry = makeRegistry(dutyList);
12
13 export function runnerOf(app: App): Runner {
14 let r = runners.get(app);
15 if (r === undefined) {
16 r = makeRunner({ db: app.db, registry, file: issueFiler(app) });
17 runners.set(app, r);
18 }
19 return r;
20 }
21
22 /** Whatever is due runs; each duty is cut off at its own deadline. */
23 export const maintainTick = (app: App, now = Date.now()) => runnerOf(app).runDue(now);
24
25 const ticking = new WeakSet<App>();
26
27 /**
28 * On the autonomy clock, off its critical path: the tick starts the due duties
29 * and returns, so a slow duty never holds the sentinel, triage or review. One
30 * pass at a time per app; a tick that finds the last one going does nothing.
31 */
32 export function maintainInBackground(app: App, now: number, onError: (error: unknown) => void): void {
33 if (ticking.has(app)) return;
34 ticking.add(app);
35 maintainTick(app, now)
36 .catch(onError)
37 .finally(() => ticking.delete(app));
38 }
39
40 export function dutyBoard(app: App) {
41 return registry.all().map((d) => {
42 const s = dutyState(app.db, d.name);
43 return {
44 name: d.name,
45 trigger: d.trigger,
46 budget: d.budget,
47 enabled: d.enabled && s.enabled,
48 pausedReason: s.pausedReason,
49 lastRun: lastRun(app.db, d.name) ?? null,
50 };
51 });
52 }
53
54 export function setDutyPaused(app: App, name: string, paused: boolean, by: string): boolean {
55 if (registry.get(name) === undefined) return false;
56 if (paused) pauseDuty(app.db, name, `paused by ${by}`);
57 else resumeDuty(app.db, name);
58 return true;
59 }
60
61 export const dutyRuns = (app: App, name?: string) => listRuns(app.db, name);
src/maintain/store.ts added +117
@@ -0,0 +1,117 @@
1 /** The maintainer's tables (#7554): duty switches, run rows, and the issue each finding key went to. */
2
3 import type { Database } from "bun:sqlite";
4 import type { Action, Finding, Outcome, ProbeRecord } from "./duty.ts";
5
6 export interface DutyState {
7 readonly name: string;
8 readonly enabled: boolean;
9 readonly pausedReason: string | null;
10 readonly errors: number;
11 }
12
13 export interface RunRow {
14 readonly id: string;
15 readonly duty: string;
16 readonly started: string;
17 readonly finished: string;
18 readonly findings: Finding[];
19 readonly actions: Action[];
20 readonly probes: ProbeRecord[];
21 readonly outcome: Outcome;
22 readonly cost: number;
23 readonly detail: string | null;
24 }
25
26 export function dutyState(db: Database, name: string): DutyState {
27 const row = db
28 .query<{ enabled: number; paused_reason: string | null; errors: number }, [string]>(
29 "SELECT enabled, paused_reason, errors FROM maintenance_duty WHERE name = ?1",
30 )
31 .get(name);
32 return { name, enabled: row === null || row.enabled === 1, pausedReason: row?.paused_reason ?? null, errors: row?.errors ?? 0 };
33 }
34
35 function setState(db: Database, name: string, enabled: boolean, reason: string | null, errors: number): void {
36 db.query(
37 `INSERT INTO maintenance_duty (name, enabled, paused_reason, errors) VALUES (?1, ?2, ?3, ?4)
38 ON CONFLICT(name) DO UPDATE SET enabled = ?2, paused_reason = ?3, errors = ?4`,
39 ).run(name, enabled ? 1 : 0, reason, errors);
40 }
41
42 export const pauseDuty = (db: Database, name: string, reason: string): void =>
43 setState(db, name, false, reason, dutyState(db, name).errors);
44 export const resumeDuty = (db: Database, name: string): void => setState(db, name, true, null, 0);
45 export const setErrors = (db: Database, name: string, errors: number): void => {
46 const s = dutyState(db, name);
47 setState(db, name, s.enabled, s.pausedReason, errors);
48 };
49
50 export function recordRun(db: Database, row: RunRow): void {
51 db.query(
52 `INSERT INTO maintenance_run (id, duty, started, finished, findings, actions, probes, outcome, cost, detail)
53 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)`,
54 ).run(
55 row.id, row.duty, row.started, row.finished, JSON.stringify(row.findings), JSON.stringify(row.actions),
56 JSON.stringify(row.probes), row.outcome, row.cost, row.detail,
57 );
58 }
59
60 export function listRuns(db: Database, duty?: string, limit = 50): RunRow[] {
61 const rows = db
62 .query<Record<string, string | number | null>, [string | null, number]>(
63 `SELECT * FROM maintenance_run WHERE (?1 IS NULL OR duty = ?1) ORDER BY started DESC, id DESC LIMIT ?2`,
64 )
65 .all(duty ?? null, limit);
66 return rows.map((r) => ({
67 id: String(r.id), duty: String(r.duty), started: String(r.started), finished: String(r.finished),
68 findings: JSON.parse(String(r.findings)), actions: JSON.parse(String(r.actions)),
69 probes: JSON.parse(String(r.probes)), outcome: String(r.outcome) as Outcome,
70 cost: Number(r.cost), detail: r.detail === null ? null : String(r.detail),
71 }));
72 }
73
74 /** Runs started and dollars spent by a duty since a moment (the day's budget). */
75 export function usedSince(db: Database, duty: string, sinceIso: string): { runs: number; usd: number } {
76 const row = db
77 .query<{ runs: number; usd: number | null }, [string, string]>(
78 "SELECT COUNT(*) AS runs, SUM(cost) AS usd FROM maintenance_run WHERE duty = ?1 AND started >= ?2 AND outcome != 'budget'",
79 )
80 .get(duty, sinceIso);
81 return { runs: row?.runs ?? 0, usd: row?.usd ?? 0 };
82 }
83
84 export function lastRun(db: Database, duty: string): RunRow | undefined {
85 return listRuns(db, duty, 1)[0];
86 }
87
88 export const runIdsBefore = (db: Database, sinceIso: string, limit: number): string[] =>
89 db.query<{ id: string }, [string, number]>("SELECT id FROM maintenance_run WHERE started < ?1 ORDER BY started LIMIT ?2").all(sinceIso, limit).map((r) => r.id);
90 export const deleteRun = (db: Database, id: string): void => void db.query("DELETE FROM maintenance_run WHERE id = ?1").run(id);
91 export const runExists = (db: Database, id: string): boolean =>
92 db.query("SELECT 1 FROM maintenance_run WHERE id = ?1").get(id) !== null;
93
94 export interface TrackedFinding {
95 readonly issueId: string;
96 /** When the issue was last opened or commented on for this key. */
97 readonly said: string;
98 /** What that last word carried, to tell a changed finding from a repeated one. */
99 readonly evidence: string;
100 }
101
102 export function trackedFinding(db: Database, key: string): TrackedFinding | undefined {
103 const row = db
104 .query<{ issue_id: string; last_seen: string; evidence: string }, [string]>(
105 "SELECT issue_id, last_seen, evidence FROM maintenance_finding WHERE key = ?1",
106 )
107 .get(key);
108 return row === null ? undefined : { issueId: row.issue_id, said: row.last_seen, evidence: row.evidence };
109 }
110
111 /** Records that the issue for a key was opened or commented on at `at` with this evidence. */
112 export function trackFinding(db: Database, key: string, issueId: string, at: string, evidence: string): void {
113 db.query(
114 `INSERT INTO maintenance_finding (key, issue_id, first_seen, last_seen, evidence) VALUES (?1, ?2, ?3, ?3, ?4)
115 ON CONFLICT(key) DO UPDATE SET issue_id = ?2, last_seen = ?3, evidence = ?4`,
116 ).run(key, issueId, at, evidence);
117 }
src/tui/screens/entries.ts +2
@@ -27,6 +27,7 @@ import { entry as forges } from "./forges.ts";
2727 import { entry as homePins } from "./home_pins.ts";
2828 import { entry as invites } from "./invites.ts";
2929 import { entry as limits } from "./limits.ts";
30 import { entry as maintain } from "./maintain.ts";
3031 import { modelCeilingEntry, modelGrantEntry } from "./model.ts";
3132 import { entry as orgGrants } from "./orggrants.ts";
3233 import { entry as orgTeams } from "./orgteams.ts";
@@ -73,6 +74,7 @@ export const ENTRIES: readonly PaletteEntry[] = [
7374 telemetry,
7475 resilience,
7576 valves,
77 maintain,
7678 access,
7779 audit,
7880 secrets,
src/tui/screens/maintain.ts added +72
@@ -0,0 +1,72 @@
1 /**
2 * The maintainer's duties in the terminal, a forge admin's who is a person:
3 * one row per duty with its trigger, budget, switch and last run, from the
4 * same `dutyBoard` as `/maintain` and the API. `p` pauses or resumes the duty
5 * under the cursor.
6 */
7
8 import { dutyBoard, setDutyPaused } from "../../maintain/service.ts";
9 import type { Ctx, Screen } from "../app/app.ts";
10 import { binding } from "../app/keys.ts";
11 import type { Session } from "../session.ts";
12 import { style } from "../term/style.ts";
13 import { truncate } from "../term/width.ts";
14 import { fill, len, split } from "../ui/layout.ts";
15 import { ListState, drawList, type ListRow } from "./common.ts";
16 import type { PaletteEntry } from "./entries.ts";
17
18 type Duty = ReturnType<typeof dutyBoard>[number];
19
20 const mayMaintain = (f: Session): boolean => f.user?.isAdmin === true && f.user.kind !== "agent";
21
22 function rowOf(d: Duty): ListRow {
23 const last = d.lastRun === null ? "has not run" : `last run ${d.lastRun.started.slice(0, 16).replace("T", " ")} ${d.lastRun.outcome}`;
24 return {
25 title: `${d.name} ${d.enabled ? "on" : "paused"}`,
26 meta: `every ${String(Math.round(d.trigger.every / 60_000))} min · ${String(d.budget.runsPerDay)} runs, $${d.budget.usdPerDay.toFixed(2)} a day`,
27 note: `${last}${d.pausedReason === null ? "" : ` · ${d.pausedReason}`}`,
28 };
29 }
30
31 export function maintainScreen(f: Session, ctx: Ctx): Screen {
32 const state = new ListState();
33 let duties: readonly Duty[] = [];
34 const reload = (): void => {
35 duties = mayMaintain(f) ? dutyBoard(f.app) : [];
36 ctx.invalidate();
37 };
38 return {
39 title: "Maintainer",
40 keys: [binding(["j", "k"], "move cursor"), binding(["p"], "pause / resume")],
41 load() {
42 reload();
43 return Promise.resolve();
44 },
45 render(area, s) {
46 const c = ctx.theme.c;
47 const [head, list] = split(area, "v", [len(1), fill(1)]);
48 s.text(head!.x, head!.y, truncate("scheduled duties: each runs inside its budget and proposes only through issues and pulls", head!.w), style(c.mutedFg, c.bg), head!.x + head!.w);
49 drawList(s, list!, c, state, duties.map(rowOf));
50 },
51 key(e) {
52 if (e.key !== "p") return state.key(e, duties.length);
53 const d = duties[state.index];
54 if (d !== undefined && mayMaintain(f) && f.user !== undefined) {
55 setDutyPaused(f.app, d.name, d.enabled, f.user.username);
56 ctx.toast(`${d.name} ${d.enabled ? "paused" : "resumed"}`);
57 reload();
58 }
59 return true;
60 },
61 };
62 }
63
64 /** The maintainer's duties: a forge admin's who is a person. */
65 export const entry: PaletteEntry = {
66 id: "maintain",
67 title: "Maintainer",
68 hint: "scheduled duties, their budgets and last runs; pause or resume one",
69 after: ["valves", "sentinel"],
70 offered: mayMaintain,
71 run: (session, ctx) => ctx.push(maintainScreen(session, ctx)),
72 };
src/web/pages/flow.ts +1 −1
@@ -82,7 +82,7 @@ export function flowPage(ctx: Ctx): Response {
8282 if (user === undefined) return signInFirst(ctx);
8383 if (!user.isAdmin || user.kind === "agent") return notFoundPage(ctx);
8484 const p = readPipes(ctx.app.db, user.id);
85 const body = html`<div class="page-head"><h1>Flow</h1>${btn("Boards", { href: "/boards", variant: "ghost" })}</div>
85 const body = html`<div class="page-head"><h1>Flow</h1>${btn("Maintainer", { href: "/maintain", variant: "ghost" })}${btn("Boards", { href: "/boards", variant: "ghost" })}</div>
8686 <p class="mb">Money flows from the left to shipped on the right, as wide as this week's real spend. Every repository has a valve: drag it to give the repository a share of the week, all the way down to shut. The crew does exactly what the valves say, from the next tick, and nothing but you turns one.</p>
8787 ${card(html`<div class="card-body">${pipesSvg(p)}
8888 <p class="muted small">${money(p.usd)} spent in the last 7 days; ${plural(p.shipped, "pull")} shipped.</p></div>`)}
src/web/pages/maintain.ts added +70
@@ -0,0 +1,70 @@
1 /**
2 * /maintain: the maintainer's duties for a forge admin who is a person: each
3 * duty's trigger, budget, switch and last run, the latest runs, and a form to
4 * pause or resume one. Same board as `GET /api/v1/maintain/duties` and
5 * `tui/screens/maintain.ts` (`maintain/service.ts`); anyone else gets a 404.
6 */
7
8 import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
9 import type { Ctx } from "../../http/context.ts";
10 import { dutyBoard, dutyRuns, setDutyPaused } from "../../maintain/service.ts";
11 import { notFoundPage } from "../chrome.ts";
12 import { readForm } from "../form.ts";
13 import { html, when } from "../html.ts";
14 import { flashTo, page } from "../layout.ts";
15 import { badge, btn, card, icon, row, time } from "../ui.ts";
16
17 type Duty = ReturnType<typeof dutyBoard>[number];
18
19 const every = (ms: number): string => (ms % 3_600_000 === 0 ? `every ${String(ms / 3_600_000)} h` : `every ${String(Math.round(ms / 60_000))} min`);
20
21 function dutyRow(d: Duty) {
22 const verb = d.enabled ? "pause" : "resume";
23 return row({
24 lead: icon("activity"),
25 title: html`${d.name} ${d.enabled ? badge("on") : badge("paused", { tone: "attn" })}
26 <span class="muted small">${every(d.trigger.every)} · ${String(d.budget.runsPerDay)} runs and $${d.budget.usdPerDay.toFixed(2)} a day</span>`,
27 meta: html`${when(d.pausedReason !== null, () => html`<p class="muted small">${d.pausedReason}</p>`)}
28 <p class="muted small">${d.lastRun === null ? "Has not run." : html`Last run ${time(d.lastRun.started)}: ${d.lastRun.outcome}${d.lastRun.detail === null ? "" : `, ${d.lastRun.detail}`}.`}</p>
29 <form method="post" action="/maintain/duties/${d.name}/${verb}">
30 ${btn(d.enabled ? "Pause" : "Resume", { size: "sm", label: `${d.enabled ? "Pause" : "Resume"} the ${d.name} duty` })}
31 </form>`,
32 });
33 }
34
35 // GET /maintain
36 export function maintainPage(ctx: Ctx): Response {
37 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
38 const user = ctx.auth.user;
39 if (user === undefined || !user.isAdmin || user.kind === "agent") return notFoundPage(ctx);
40 const duties = dutyBoard(ctx.app);
41 const runs = dutyRuns(ctx.app).slice(0, 20);
42 const body = html`<div class="page-head"><h1>Maintainer</h1>${btn("Boards", { href: "/boards", variant: "ghost" })}</div>
43 <p class="mb">Scheduled duties. Each runs inside its budget, leaves a probe behind every finding and action, and proposes only through issues and pulls; nothing here merges.</p>
44 ${card(html`<ul class="list">${duties.map(dutyRow)}</ul>`, { pad: false, head: html`${icon("activity")}<h2>Duties</h2>` })}
45 ${card(
46 runs.length === 0
47 ? html`<div class="card-body"><p class="muted">No duty has run yet.</p></div>`
48 : html`<ul class="list">${runs.map((r) =>
49 row({
50 title: html`${r.duty} <span class="muted small">${r.outcome} · ${time(r.started)} · ${String(r.findings.length)} findings, ${String(r.actions.length)} actions</span>`,
51 ...(r.detail === null ? {} : { meta: html`<p class="muted small">${r.detail}</p>` }),
52 }),
53 )}</ul>`,
54 { pad: false, head: html`${icon("activity")}<h2>Recent runs</h2>` },
55 )}`;
56 const rendering = performance.now();
57 const response = page({ ctx, title: "Maintainer", body });
58 notePhase(ctx.request, "render", performance.now() - rendering);
59 return response;
60 }
61
62 // POST /maintain/duties/:name/pause and /resume
63 export const switchDuty = (paused: boolean) => async (ctx: Ctx): Promise<Response> => {
64 if (ctx.auth.user === undefined || !ctx.auth.user.isAdmin || ctx.auth.user.kind === "agent") return notFoundPage(ctx);
65 const form = await readForm(ctx, "admin");
66 if (form instanceof Response) return form;
67 const name = ctx.params.name ?? "";
68 if (!setDutyPaused(ctx.app, name, paused, ctx.auth.user.username)) return notFoundPage(ctx);
69 return flashTo(ctx, "/maintain", { message: `${name} ${paused ? "paused" : "resumed"}.` });
70 };
src/web/studio/crew.ts +2
@@ -62,6 +62,7 @@ const ROLE_WORD: Record<CrewRole, string> = {
6262 builder: "builds",
6363 reviewer: "reviews",
6464 planner: "plans",
65 maintainer: "keeps up",
6566 };
6667
6768 /**
@@ -139,6 +140,7 @@ const SEAT_TITLE: Record<CrewRole, string> = {
139140 planner: "Planners",
140141 builder: "Builders",
141142 reviewer: "Reviewers",
143 maintainer: "Maintainers",
142144 };
143145
144146 /**
test/forge-looks.test.ts +1
@@ -56,6 +56,7 @@ const NOT_A_PAGE: Record<string, string> = {
5656 "/events": "a live event stream that never ends",
5757 "/boards": "the list of boards; /board is pictured, and the slot went to the preview seed's repository as its owner (#8865); covered by test/boards-page.test.ts",
5858 "/changelog": "the merged changes in words; /releases is pictured, and the slot went to the preview seed's pull as its owner (#8865); covered by test/changelog.test.ts",
59 "/maintain": "the maintainer's duties for an admin; the cap of 24 looks is full; covered by the maintain tests",
5960 "/search": "a search box; its slot went to the preview seed's /next as its owner (#8866)",
6061 "/contribute": "a static page about how to help; its slot went to the preview seed's /bets as its owner (#8866)",
6162 "/migrate": "an import form, nothing to picture until a job runs; the look slot went to /repos",
test/helpers/maintain.ts added +28
@@ -0,0 +1,28 @@
1 import { Database } from "bun:sqlite";
2 import maintenance from "../../src/core/migrations/20261103150000-maintenance.ts";
3 import { type Duty, type FindingInput, duty } from "../../src/maintain/duty.ts";
4 import { makeRegistry } from "../../src/maintain/registry.ts";
5 import { makeRunner } from "../../src/maintain/runner.ts";
6 import type { Finding } from "../../src/maintain/duty.ts";
7
8 export const NOW = Date.parse("2026-11-02T12:00:00Z");
9 export const HOUR = 3_600_000;
10
11 export function maintainer(duties: Duty[], filed: Finding[] = []) {
12 const db = new Database(":memory:");
13 db.exec(maintenance);
14 const runner = makeRunner({
15 db,
16 registry: makeRegistry(duties),
17 file: (f) => {
18 filed.push(f);
19 return `#${filed.length}`;
20 },
21 });
22 return { db, runner };
23 }
24
25 export const probed = (ctx: { probe: (q: string, v: number) => unknown }, key = "k"): FindingInput =>
26 ({ key, title: `finding ${key}`, evidence: ["e"], probe: ctx.probe("SELECT 1", 1) }) as FindingInput;
27
28 export { duty };
test/maintain-api.test.ts added +70
@@ -0,0 +1,70 @@
1 /** The board's switch for a duty, over the API, and the issue a finding is filed to (#7554). */
2
3 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
4 import { mkdtemp, rm } from "node:fs/promises";
5 import { tmpdir } from "node:os";
6 import { join } from "node:path";
7 import { createApp, type App } from "../src/app.ts";
8 import { createToken } from "../src/core/tokens.ts";
9 import { createUser, getUserByName } from "../src/core/users.ts";
10 import { serve, type Servers } from "../src/http/server.ts";
11 import { runnerOf } from "../src/maintain/service.ts";
12 import { dutyList } from "../src/maintain/duties/index.ts";
13 import { quietLogs } from "./helpers/globals.ts";
14
15 quietLogs();
16 const PASS = "a-long-maintain-passphrase";
17
18 describe("maintainer over HTTP", () => {
19 let dataDir = "";
20 let app: App;
21 let servers: Servers;
22 const tokenOf = (name: string, scope: "ro" | "admin" = "admin") => createToken(app.db, getUserByName(app.db, name)!.id, "t", scope).token;
23 const call = (method: string, path: string, token: string | null) =>
24 fetch(`${servers.url}/api/v1/maintain/${path}`, { method, headers: token ? { authorization: `Bearer ${token}` } : {} });
25
26 beforeAll(async () => {
27 dataDir = await mkdtemp(join(tmpdir(), "forge-maintain-"));
28 app = createApp({ dataDir, port: 0 });
29 servers = await serve(app);
30 for (const [username, isAdmin] of [["alice", true], ["bob", false]] as const)
31 await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@x.test`, password: PASS, isAdmin });
32 }, 30_000);
33
34 afterAll(async () => {
35 servers.stop();
36 app.close();
37 await rm(dataDir, { recursive: true, force: true });
38 });
39
40 test("an admin lists duties, pauses one with a reason, and resumes it", async () => {
41 const name = dutyList[0]!.name;
42 const listed = (await (await call("GET", "duties", tokenOf("alice", "ro"))).json()) as any;
43 expect(listed.duties.map((d: any) => d.name)).toContain(name);
44 const paused = (await (await call("POST", `duties/${name}/pause`, tokenOf("alice"))).json()) as any;
45 expect(paused.duties.find((d: any) => d.name === name)).toMatchObject({ enabled: false, pausedReason: "paused by alice" });
46 expect(await runnerOf(app).runDue(Date.now() + 10 * 86_400_000)).toEqual([]);
47 const resumed = (await (await call("POST", `duties/${name}/resume`, tokenOf("alice"))).json()) as any;
48 expect(resumed.duties.find((d: any) => d.name === name).enabled).toBe(true);
49 });
50
51 test("a read-only token cannot pause; a plain member and a stranger are told nothing is there", async () => {
52 const name = dutyList[0]!.name;
53 expect((await call("POST", `duties/${name}/pause`, tokenOf("alice", "ro"))).status).toBe(403);
54 expect((await call("GET", "duties", tokenOf("bob"))).status).toBe(404);
55 expect((await call("GET", "runs", null)).status).toBe(404);
56 expect((await call("POST", "duties/nope/pause", tokenOf("alice"))).status).toBe(404);
57 });
58
59 test("the scheduled run leaves a row the API reads", async () => {
60 await runnerOf(app).runDue(Date.now() + 100 * 86_400_000);
61 const runs = (await (await call("GET", `runs?duty=${dutyList[0]!.name}`, tokenOf("alice", "ro"))).json()) as any;
62 expect(runs.runs.length).toBeGreaterThan(0);
63 });
64
65 test("the routes are in the OpenAPI document", async () => {
66 const doc = (await (await fetch(`${servers.url}/api/v1/openapi.json`)).json()) as any;
67 expect(doc.paths["/api/v1/maintain/duties"].get).toBeDefined();
68 expect(doc.paths["/api/v1/maintain/duties/{name}/pause"].post).toBeDefined();
69 });
70 });
test/maintain-budget.test.ts added +92
@@ -0,0 +1,92 @@
1 /** A duty over budget stops and records "budget" as the outcome (#7554). */
2
3 import { describe, expect, test } from "bun:test";
4 import { HOUR, NOW, duty, maintainer } from "./helpers/maintain.ts";
5 import { listRuns } from "../src/maintain/store.ts";
6 import type { Budget } from "../src/maintain/duty.ts";
7
8 const budget = (b: Partial<Budget>): Budget => ({ runsPerDay: 100, usdPerDay: 1, cpuMsPerRun: 10_000, netCallsPerRun: 2, ...b });
9
10 describe("budget", () => {
11 test("runs per day: the run past the budget does not run and says budget", async () => {
12 let ran = 0;
13 const d = duty({ name: "few", trigger: { every: 1 }, budget: budget({ runsPerDay: 2 }), handler: () => { ran++; return {}; } });
14 const { db, runner } = maintainer([d]);
15 for (let i = 0; i < 4; i++) await runner.runDue(NOW + i * 10);
16 expect(ran).toBe(2);
17 const rows = listRuns(db, "few");
18 expect(rows.filter((r) => r.outcome === "budget")).toHaveLength(1); // said once, not each tick
19 expect(rows[0]?.outcome).toBe("budget");
20 });
21
22 test("the day rolls over", async () => {
23 const d = duty({ name: "daily", trigger: { every: 1 }, budget: budget({ runsPerDay: 1 }), handler: () => ({}) });
24 const { runner } = maintainer([d]);
25 await runner.runDue(NOW);
26 expect((await runner.runDue(NOW + HOUR))[0]?.outcome).toBe("budget");
27 expect((await runner.runDue(NOW + 25 * HOUR))[0]?.outcome).toBe("ok");
28 });
29
30 test("dollars: spending past the day's ceiling stops the run", async () => {
31 const d = duty({
32 name: "spender",
33 trigger: { every: 1 },
34 budget: budget({ usdPerDay: 1 }),
35 handler: (ctx) => {
36 ctx.spend(0.6);
37 ctx.spend(0.6);
38 return {};
39 },
40 });
41 const { db, runner } = maintainer([d]);
42 await runner.runDue(NOW);
43 const [row] = listRuns(db);
44 expect(row?.outcome).toBe("budget");
45 expect(row?.detail).toContain("$1");
46 expect(row?.cost).toBeCloseTo(1.2);
47 });
48
49 test("network: calls past the ceiling stop the run", async () => {
50 const d = duty({ name: "chatty", trigger: { every: 1 }, budget: budget({ netCallsPerRun: 2 }), handler: (ctx) => { ctx.net(); ctx.net(); ctx.net(); return {}; } });
51 const { db, runner } = maintainer([d]);
52 await runner.runDue(NOW);
53 expect(listRuns(db)[0]?.outcome).toBe("budget");
54 });
55
56 test("time: a run past its ceiling is recorded as budget", async () => {
57 const d = duty({ name: "slow", trigger: { every: 1 }, budget: budget({ cpuMsPerRun: 5 }), handler: async () => { await Bun.sleep(30); return {}; } });
58 const { db, runner } = maintainer([d]);
59 await runner.runDue(NOW);
60 expect(listRuns(db)[0]?.outcome).toBe("budget");
61 });
62
63 test("time: a handler that never settles is cut off at its deadline and frees the duty", async () => {
64 const d = duty({ name: "hung", trigger: { every: 1 }, budget: budget({ cpuMsPerRun: 20 }), handler: () => new Promise(() => {}) });
65 const { db, runner } = maintainer([d]);
66 const started = performance.now();
67 await runner.runDue(NOW);
68 expect(performance.now() - started).toBeLessThan(1000);
69 expect(listRuns(db)[0]).toMatchObject({ outcome: "budget", detail: "took longer than 20 ms" });
70 expect(await runner.runDue(NOW + 10)).toHaveLength(1); // not stuck running
71 });
72
73 test("an abandoned handler's late calls do nothing", async () => {
74 let late: unknown;
75 const d = duty({ name: "late", trigger: { every: 1 }, budget: budget({ cpuMsPerRun: 10 }), handler: async (ctx) => {
76 await Bun.sleep(40);
77 try { ctx.spend(1); late = "spent"; } catch (e) { late = e instanceof Error ? e.message : "?"; }
78 return {};
79 } });
80 const { runner } = maintainer([d]);
81 await runner.runDue(NOW);
82 await Bun.sleep(60);
83 expect(late).toBe("the run has ended");
84 });
85
86 test("a budget stop is not an error: it never pauses the duty", async () => {
87 const d = duty({ name: "chat", trigger: { every: 1 }, budget: budget({ netCallsPerRun: 0 }), handler: (ctx) => { ctx.net(); return {}; } });
88 const { db, runner } = maintainer([d]);
89 for (let i = 0; i < 4; i++) await runner.runDue(NOW + i * 10);
90 expect(db.query("SELECT enabled FROM maintenance_duty").all()).toEqual([]);
91 });
92 });
test/maintain-canary.test.ts added +53
@@ -0,0 +1,53 @@
1 /** A bulk action touches one item, waits for its probe, then continues (#7554). */
2
3 import { describe, expect, test } from "bun:test";
4 import { NOW, duty, maintainer } from "./helpers/maintain.ts";
5 import { listRuns } from "../src/maintain/store.ts";
6 import { BULK_CAP, type DutyContext } from "../src/maintain/duty.ts";
7
8 const bulky = (items: number[], touched: number[], passes: (n: number) => boolean) =>
9 duty({
10 name: "bulk",
11 trigger: { every: 1 },
12 handler: async (ctx: DutyContext) => {
13 await ctx.bulk(items, {
14 what: "touch",
15 target: String,
16 apply: (n) => void touched.push(n),
17 check: (n) => ({ ...ctx.probe(`check ${n}`, passes(n)), pass: passes(n) }),
18 });
19 return {};
20 },
21 });
22
23 describe("canary", () => {
24 test("a passing canary lets the rest through, each with its probe", async () => {
25 const touched: number[] = [];
26 const { db, runner } = maintainer([bulky([1, 2, 3], touched, () => true)]);
27 await runner.runDue(NOW);
28 expect(touched).toEqual([1, 2, 3]);
29 const [row] = listRuns(db);
30 expect(row?.outcome).toBe("ok");
31 expect(row?.actions.map((a) => a.target)).toEqual(["1", "2", "3"]);
32 });
33
34 test("a failing canary touches nothing else", async () => {
35 const touched: number[] = [];
36 const { db, runner } = maintainer([bulky([1, 2, 3], touched, () => false)]);
37 await runner.runDue(NOW);
38 expect(touched).toEqual([1]);
39 const [row] = listRuns(db);
40 expect(row?.outcome).toBe("canary");
41 expect(row?.detail).toContain("nothing else touched");
42 expect(row?.actions).toHaveLength(1);
43 expect(row?.actions[0]?.probe.value).toBe(false);
44 });
45
46 test("a bulk is capped per run", async () => {
47 const touched: number[] = [];
48 const many = Array.from({ length: BULK_CAP + 15 }, (_, i) => i);
49 const { runner } = maintainer([bulky(many, touched, () => true)]);
50 await runner.runDue(NOW);
51 expect(touched).toHaveLength(BULK_CAP);
52 });
53 });
test/maintain-doors.test.ts added +110
@@ -0,0 +1,110 @@
1 /** The maintainer's two doors, the page and the terminal screen, both an admin's; (#7554). */
2
3 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
4 import { mkdtemp, rm } from "node:fs/promises";
5 import { tmpdir } from "node:os";
6 import { join } from "node:path";
7 import { createApp, type App } from "../src/app.ts";
8 import { createUser, type User } from "../src/core/users.ts";
9 import { serve, type Servers } from "../src/http/server.ts";
10 import { dutyList } from "../src/maintain/duties/index.ts";
11 import { dutyBoard } from "../src/maintain/service.ts";
12 import { createForgeApp, forgeCommands } from "../src/tui/forge.ts";
13 import { headlessTerminal } from "../src/tui/term/terminal.ts";
14 import { quietLogs } from "./helpers/globals.ts";
15 import { settleApp, settleUntil } from "./helpers/tui.ts";
16
17 quietLogs();
18 const PASS = "a-good-passphrase";
19 const NAME = dutyList[0]!.name;
20
21 describe("the maintainer's doors", () => {
22 let dir = "";
23 let app: App;
24 let servers: Servers;
25 let alice: User;
26 let bob: User;
27 const login = async (username: string): Promise<string> => {
28 const res = await fetch(`${servers.url}/signin`, {
29 method: "POST", redirect: "manual",
30 headers: { "content-type": "application/x-www-form-urlencoded", origin: servers.url },
31 body: new URLSearchParams({ username, password: PASS }),
32 });
33 return (res.headers.get("set-cookie") ?? "").split(";")[0] ?? "";
34 };
35 const get = (path: string, cookie: string) => fetch(`${servers.url}${path}`, { headers: { cookie }, redirect: "manual" });
36 const post = (path: string, cookie: string, origin = servers.url) =>
37 fetch(`${servers.url}${path}`, { method: "POST", redirect: "manual", headers: { cookie, origin, "content-type": "application/x-www-form-urlencoded" }, body: "" });
38 const enabled = () => dutyBoard(app).find((d) => d.name === NAME)!.enabled;
39 const identity = (user: User) => ({ sshUsername: user.username, remoteAddress: "127.0.0.1", fingerprint: "SHA256:test", user });
40
41 beforeAll(async () => {
42 dir = await mkdtemp(join(tmpdir(), "forge-maintain-doors-"));
43 app = createApp({ dataDir: dir, port: 0 });
44 servers = await serve(app);
45 const make = async (username: string, adminIfFirst: boolean) => {
46 const u = await createUser(app.db, { origin: "seed", trusted: true, username, email: `${username}@forge.local`, password: PASS, adminIfFirst });
47 if (!u.ok) throw new Error(u.error);
48 return u.value;
49 };
50 alice = await make("alice", true);
51 bob = await make("bob", false);
52 }, 30_000);
53 afterAll(async () => {
54 servers.stop();
55 app.close();
56 await rm(dir, { recursive: true, force: true });
57 });
58
59 test("the page lists the duties to an admin, and a guest or a member finds nothing", async () => {
60 const res = await get("/maintain", await login("alice"));
61 expect(res.status).toBe(200);
62 const text = await res.text();
63 expect(text).toContain(NAME);
64 expect(text).toContain(`action="/maintain/duties/${NAME}/pause"`);
65 expect((await get("/maintain", await login("bob"))).status).toBe(404);
66 expect((await get("/maintain", "")).status).toBe(404);
67 });
68
69 test("pause and resume are post forms: same-origin, admin only, and they change the switch", async () => {
70 const cookie = await login("alice");
71 expect((await post(`/maintain/duties/${NAME}/pause`, cookie, "https://evil.example")).status).toBeGreaterThanOrEqual(400);
72 expect(enabled()).toBe(true);
73 expect((await post(`/maintain/duties/${NAME}/pause`, await login("bob"))).status).toBe(404);
74 expect(enabled()).toBe(true);
75 expect((await post(`/maintain/duties/${NAME}/pause`, cookie)).status).toBe(303);
76 expect(enabled()).toBe(false);
77 expect((await get("/maintain", cookie).then((r) => r.text()))).toContain(`/maintain/duties/${NAME}/resume`);
78 expect((await post(`/maintain/duties/${NAME}/resume`, cookie)).status).toBe(303);
79 expect(enabled()).toBe(true);
80 expect((await post("/maintain/duties/nope/pause", cookie)).status).toBe(404);
81 });
82
83 const open = (u: User) => {
84 const made = createForgeApp(app, identity(u), { terminal: headlessTerminal(140, 24), exitHooks: false });
85 const ids = forgeCommands(made.session)(made.app.ctx).map((c) => c.id);
86 return { ...made, ids };
87 };
88
89 test("the terminal offers the screen to an admin only, and p pauses the duty under the cursor", async () => {
90 const guest = open(bob);
91 expect(guest.ids).not.toContain("maintain");
92 guest.app.stop?.();
93 const { app: tui, ids } = open(alice);
94 expect(ids).toContain("maintain");
95 tui.start();
96 const key = (k: string, ctrl = false) => tui.dispatch({ type: "key", key: k, ctrl, alt: false, shift: false });
97 key("k", true);
98 for (const ch of "Maintainer") key(ch);
99 await settleApp(tui);
100 key("enter");
101 await settleUntil(tui, `${NAME} on`, { timeoutMs: 4_000 });
102 key("p");
103 await settleUntil(tui, `${NAME} paused`, { timeoutMs: 4_000 });
104 expect(enabled()).toBe(false);
105 key("p");
106 await settleUntil(tui, `${NAME} on`, { timeoutMs: 4_000 });
107 expect(enabled()).toBe(true);
108 tui.stop?.();
109 });
110 });
test/maintain-file.test.ts added +91
@@ -0,0 +1,91 @@
1 /** Where a finding goes: only the maintainer files, and a still-true finding is not said again every run (#7554). */
2
3 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
4 import { mkdtemp, rm } from "node:fs/promises";
5 import { tmpdir } from "node:os";
6 import { join } from "node:path";
7 import { createRepo } from "../src/actions/repos.ts";
8 import { createApp, type App } from "../src/app.ts";
9 import { createAgentRow } from "../src/core/agents.ts";
10 import { getIssueById, listComments } from "../src/core/issues.ts";
11 import { createUser, type User } from "../src/core/users.ts";
12 import type { Finding } from "../src/maintain/duty.ts";
13 import { issueFiler } from "../src/maintain/file.ts";
14 import { admit } from "../src/maintain/probe.ts";
15 import { trackedFinding } from "../src/maintain/store.ts";
16 import { quietLogs } from "./helpers/globals.ts";
17
18 quietLogs();
19 const DAY = 86_400_000;
20 const T0 = Date.parse("2026-11-02T12:00:00Z");
21 const finding = (evidence: string[] = ["3 stale"], value = 3): Finding => ({
22 key: "stale-things", title: "Stale things", evidence,
23 probe: { query: "SELECT COUNT(*) FROM stale", value, at: "2026-11-02T12:00:00Z" },
24 });
25
26 describe("the maintainer files", () => {
27 let dir = "";
28 let app: App;
29 let alice: User;
30 const commentsOn = (key: string) => {
31 const issue = getIssueById(app.db, trackedFinding(app.db, key)!.issueId)!;
32 return listComments(app.db, issue.id).length;
33 };
34
35 beforeAll(async () => {
36 dir = await mkdtemp(join(tmpdir(), "forge-maintain-file-"));
37 app = createApp({ dataDir: dir, port: 0 });
38 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-long-maintain-passphrase", isAdmin: true });
39 if (!made.ok) throw new Error(made.error);
40 alice = made.value;
41 const repo = await createRepo(app, alice, { name: "forge", visibility: "public" });
42 if (!repo.ok) throw new Error(String(repo.error));
43 }, 30_000);
44
45 afterAll(async () => {
46 app.close();
47 await rm(dir, { recursive: true, force: true });
48 });
49
50 test("with no maintainer seated nothing is filed, and no admin speaks for it", () => {
51 const file = issueFiler(app, "alice/forge");
52 expect(() => file(finding(), T0)).toThrow("no maintainer agent");
53 expect(trackedFinding(app.db, "stale-things")).toBeUndefined();
54 });
55
56 test("a seated maintainer files as itself; the same finding is not commented again until it changes or a day passes", async () => {
57 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "maintainer", email: "[email protected]", password: "a-long-maintain-passphrase" });
58 if (!made.ok) throw new Error(made.error);
59 createAgentRow(app.db, { userId: made.value.id, roles: ["maintainer"] });
60 const file = issueFiler(app, "alice/forge");
61
62 expect(file(finding(), T0)).toMatch(/^#\d+$/);
63 const issue = getIssueById(app.db, trackedFinding(app.db, "stale-things")!.issueId)!;
64 expect(issue.authorId).toBe(made.value.id);
65 expect(commentsOn("stale-things")).toBe(0);
66
67 expect(file(finding(), T0 + 3_600_000)).toContain("(unchanged)");
68 expect(file(finding(), T0 + 5 * 3_600_000)).toContain("(unchanged)");
69 expect(commentsOn("stale-things")).toBe(0);
70
71 expect(file(finding(["4 stale"], 4), T0 + 6 * 3_600_000)).toContain("(commented)");
72 expect(commentsOn("stale-things")).toBe(1);
73
74 expect(file(finding(["4 stale"], 4), T0 + 7 * 3_600_000)).toContain("(unchanged)");
75 expect(file(finding(["4 stale"], 4), T0 + 6 * 3_600_000 + DAY)).toContain("(commented)");
76 expect(commentsOn("stale-things")).toBe(2);
77 });
78 });
79
80 describe("admit caps what a duty can say", () => {
81 const probe = { query: "SELECT 1", value: 1, at: "2026-11-02T12:00:00Z" };
82 test("a long title, long or many evidence lines, and too many findings are refused", () => {
83 const mk = (over: Partial<Finding>): Finding => ({ ...finding(), ...over, probe });
84 const r = admit([mk({ key: "t", title: "x".repeat(201) }), mk({ key: "l", evidence: ["y".repeat(501)] }), mk({ key: "n", evidence: Array(21).fill("e") }), mk({ key: "ok" })], []);
85 expect(r.findings.map((f) => f.key)).toEqual(["ok"]);
86 expect(r.refused).toHaveLength(3);
87 const many = admit(Array.from({ length: 25 }, (_, i) => mk({ key: `k${i}` })), []);
88 expect(many.findings).toHaveLength(20);
89 expect(many.refused).toHaveLength(5);
90 });
91 });
test/maintain-no-land.test.ts added +53
@@ -0,0 +1,53 @@
1 /** The maintainer role has no path to merge or to push main (#7554). */
2
3 import { describe, expect, test } from "bun:test";
4 import { readdirSync, readFileSync } from "node:fs";
5 import { join } from "node:path";
6 import { Database } from "bun:sqlite";
7 import { isCrewRole } from "../src/core/agents.ts";
8
9 const root = join(import.meta.dir, "../src/maintain");
10 const sources = (dir: string): string[] =>
11 readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
12 e.isDirectory() ? sources(join(dir, e.name)) : e.name.endsWith(".ts") ? [join(dir, e.name)] : [],
13 );
14
15 describe("the maintainer proposes, a person lands", () => {
16 test("maintainer is a crew role, the same kind of agent as a builder", () => {
17 expect(isCrewRole("maintainer")).toBe(true);
18 });
19
20 test("nothing under src/maintain imports a way to merge, push or run git", () => {
21 const banned = [/mergePull/, /core\/merges/, /git\/(receive|push|hooks)/, /Bun\.spawn/, /node:child_process/, /\bpush\b.*\bmain\b/, /\beval\(/];
22 for (const file of sources(root)) {
23 const text = readFileSync(file, "utf8");
24 for (const rule of banned) expect([file, rule.test(text)]).toEqual([file, false]);
25 }
26 });
27
28 test("a duty's context offers named accessors and no database handle", async () => {
29 const { maintainer, NOW, duty } = await import("./helpers/maintain.ts");
30 let ctxSeen: Record<string, unknown> = {};
31 const { runner } = maintainer([duty({ name: "peek", trigger: { every: 1 }, handler: (ctx) => { ctxSeen = ctx as unknown as Record<string, unknown>; return {}; } })]);
32 await runner.runDue(NOW);
33 expect(Object.keys(ctxSeen).sort()).toEqual(["bulk", "net", "now", "probe", "runs", "spend"]);
34 expect(Object.keys(ctxSeen.runs as object).sort()).toEqual(["before", "has", "prune"]);
35 const handles = [ctxSeen, ctxSeen.runs].flatMap((o) => Object.values(o as object)).filter((v) => v instanceof Database);
36 expect(handles).toEqual([]);
37 });
38
39 test("duty files import no database, store or core module: they get what the context hands them", () => {
40 for (const file of sources(join(root, "duties")).filter((f) => !f.endsWith("index.ts"))) {
41 const imports = [...readFileSync(file, "utf8").matchAll(/from "([^"]+)"/g)].map((m) => m[1]);
42 expect([file, imports.filter((i) => i !== "../duty.ts")]).toEqual([file, []]);
43 }
44 });
45
46 test("a duty cannot write what it was not handed: merge state, tokens and users stay out of reach", async () => {
47 const { maintainer, NOW, duty } = await import("./helpers/maintain.ts");
48 let reached: unknown = "untouched";
49 const { runner } = maintainer([duty({ name: "grab", trigger: { every: 1 }, handler: (ctx) => { reached = (ctx as unknown as { db?: unknown }).db; return {}; } })]);
50 await runner.runDue(NOW);
51 expect(reached).toBeUndefined();
52 });
53 });
test/maintain-probe-required.test.ts added +39
@@ -0,0 +1,39 @@
1 /** A finding or an action without the probe behind it is refused (#7554). */
2
3 import { describe, expect, test } from "bun:test";
4 import { NOW, duty, maintainer, probed } from "./helpers/maintain.ts";
5 import { listRuns } from "../src/maintain/store.ts";
6 import { validProbe } from "../src/maintain/probe.ts";
7 import type { Finding } from "../src/maintain/duty.ts";
8
9 describe("probe required", () => {
10 test("a finding with no probe is refused, one with a probe is kept and filed", async () => {
11 const filed: Finding[] = [];
12 const d = duty({
13 name: "mixed",
14 trigger: { every: 1 },
15 handler: (ctx) => ({
16 findings: [{ key: "bare", title: "no probe", evidence: [], probe: undefined }, probed(ctx, "backed")],
17 actions: [{ what: "fix", target: "t", probe: undefined }],
18 }),
19 });
20 const { db, runner } = maintainer([d], filed);
21 await runner.runDue(NOW);
22 const [row] = listRuns(db);
23 expect(row?.outcome).toBe("refused");
24 expect(row?.findings.map((f) => f.key)).toEqual(["backed"]);
25 expect(row?.actions).toEqual([]);
26 expect(row?.detail).toContain("finding bare: no probe");
27 expect(row?.detail).toContain("action fix t: no probe");
28 expect(filed.map((f) => f.key)).toEqual(["backed"]);
29 });
30
31 test("a probe needs a query, a finite value and a time", () => {
32 const ok = { query: "SELECT 1", value: 1, at: "2026-11-02T12:00:00Z" };
33 expect(validProbe(ok)).toBe(true);
34 expect(validProbe({ ...ok, query: " " })).toBe(false);
35 expect(validProbe({ ...ok, value: Number.NaN })).toBe(false);
36 expect(validProbe({ ...ok, at: "yesterday-ish" })).toBe(false);
37 expect(validProbe(undefined)).toBe(false);
38 });
39 });
test/maintain-runner.test.ts added +94
@@ -0,0 +1,94 @@
1 /** A duty registered in one place runs on schedule, serialized, and leaves a run row (#7554). */
2
3 import { describe, expect, test } from "bun:test";
4 import { HOUR, NOW, duty, maintainer, probed } from "./helpers/maintain.ts";
5 import { listRuns, dutyState, resumeDuty } from "../src/maintain/store.ts";
6 import { makeRegistry } from "../src/maintain/registry.ts";
7 import { dutyList } from "../src/maintain/duties/index.ts";
8 import type { Finding } from "../src/maintain/duty.ts";
9
10 describe("the duty runner", () => {
11 test("runs a due duty and leaves a row with findings, actions and probes", async () => {
12 const filed: Finding[] = [];
13 const d = duty({
14 name: "look",
15 trigger: { every: HOUR },
16 handler: (ctx) => ({
17 findings: [probed(ctx, "a")],
18 actions: [{ what: "note", target: "x", probe: ctx.probe("SELECT 2", 2) }],
19 }),
20 });
21 const { db, runner } = maintainer([d], filed);
22 const ran = await runner.runDue(NOW);
23 expect(ran).toHaveLength(1);
24 const [row] = listRuns(db, "look");
25 expect(row?.outcome).toBe("ok");
26 expect(row?.findings.map((f) => f.key)).toEqual(["a"]);
27 expect(row?.actions[0]?.target).toBe("x");
28 expect(row?.probes.map((p) => p.value)).toEqual([1, 2]);
29 expect(filed.map((f) => f.key)).toEqual(["a"]);
30 });
31
32 test("waits for its interval, then runs again", async () => {
33 const { db, runner } = maintainer([duty({ name: "tick", trigger: { every: HOUR }, handler: () => ({}) })]);
34 await runner.runDue(NOW);
35 expect(await runner.runDue(NOW + HOUR / 2)).toHaveLength(0);
36 expect(await runner.runDue(NOW + HOUR)).toHaveLength(1);
37 expect(listRuns(db)).toHaveLength(2);
38 });
39
40 test("a duty never overlaps itself", async () => {
41 let release = () => {};
42 let starts = 0;
43 const d = duty({
44 name: "slow",
45 trigger: { every: 1 },
46 handler: () => {
47 starts++;
48 return new Promise((r) => (release = () => r({})));
49 },
50 });
51 const { runner } = maintainer([d]);
52 const first = runner.runDuty(d, NOW);
53 expect(await runner.runDuty(d, NOW + 5)).toBeUndefined();
54 release();
55 await first;
56 expect(starts).toBe(1);
57 });
58
59 test("a switched-off duty does not run", async () => {
60 const { runner } = maintainer([duty({ name: "off", trigger: { every: 1 }, enabled: false, handler: () => ({}) })]);
61 expect(await runner.runDue(NOW)).toHaveLength(0);
62 });
63
64 test("three errors in a row pause the duty and say why; resume clears it", async () => {
65 const d = duty({ name: "bad", trigger: { every: 1 }, handler: () => { throw new Error("boom"); } });
66 const { db, runner } = maintainer([d]);
67 for (let i = 0; i < 3; i++) await runner.runDue(NOW + i * 10);
68 const state = dutyState(db, "bad");
69 expect(state.enabled).toBe(false);
70 expect(state.pausedReason).toContain("3 times");
71 expect(state.pausedReason).toContain("boom");
72 expect(await runner.runDue(NOW + 100)).toHaveLength(0);
73 resumeDuty(db, "bad");
74 expect(await runner.runDue(NOW + 200)).toHaveLength(1);
75 });
76
77 test("a success resets the error count", async () => {
78 let fail = true;
79 const d = duty({ name: "flaky", trigger: { every: 1 }, handler: () => { if (fail) throw new Error("x"); return {}; } });
80 const { db, runner } = maintainer([d]);
81 await runner.runDue(NOW);
82 await runner.runDue(NOW + 10);
83 fail = false;
84 await runner.runDue(NOW + 20);
85 expect(dutyState(db, "flaky").errors).toBe(0);
86 });
87
88 test("the registry refuses a twin and a bad name; the shipped duties register", () => {
89 const d = duty({ name: "one", trigger: { every: 1 }, handler: () => ({}) });
90 expect(() => makeRegistry([d, d])).toThrow("twice");
91 expect(() => makeRegistry([duty({ name: "Bad Name", trigger: { every: 1 }, handler: () => ({}) })])).toThrow();
92 expect(makeRegistry(dutyList).all().length).toBeGreaterThan(0);
93 });
94 });
test/palette-roster.test.ts +1
@@ -86,6 +86,7 @@ test("a site-admin person is offered the whole roster", () => {
8686 ["flow", "Flow", "the pipeline's bottleneck and throughput"],
8787 ["system", "System", "the machine now: CPU, memory, disks, processes"],
8888 ["valves", "Valves", "the week's budget as a valve per repository; turn one and the crew obeys"],
89 ["maintain", "Maintainer", "scheduled duties, their budgets and last runs; pause or resume one"],
8990 ["telemetry", "Telemetry", "which agents may read flow and system; enter flips the grant"],
9091 ["capacity", "Capacity", "concurrency and guards, live; e changes a settable one"],
9192 ["resilience", "Resilience", "where snapshots go and the mirror; each protection green, red or untested"],

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs