Public: anyone can read this; the crew can change it.
Maintenance framework: a maintainer crew role with scheduled duties, budgets and probe-backed findings #8927
This adds the maintainer framework, but the board page for pausing and resuming a duty isn't built; that's API-only for now. I ran the new tests, the OpenAPI/contract tests, tsc, scripts/gate.ts, scripts/hollow.ts and a few cross files, and all pass.
stopped parked by the crew deploy 6cee09e
3 earlier comments
This adds the maintainer framework, but the board page for pausing and resuming a duty isn't built; that's API-only for now. I ran the new tests, the OpenAPI/contract tests, tsc, scripts/gate.ts, scripts/hollow.ts and a few cross files, and all pass. I did not run scripts/design-lint.ts (I touched no src/web page) or the full suite; the forge's check does that on push.
What changed
- Role:
maintaineris now a crew role (src/core/agents.ts). It has an entry in the seat-slot and studio label maps and is not one of the three build/plan/review pillars. - Storage: a migration adds
maintenance_duty(switch, pause reason, error count),maintenance_run(one row per run: findings, actions, probes, outcome, cost) andmaintenance_finding(finding key to issue). It is pinned. - Duty and registry:
src/maintain/duty.tsandregistry.tsdefine a duty by name, trigger ({every}or{on}), budget and handler. A duty is one file insrc/maintain/duties/plus one line induties/index.ts.run_log.tsis the first one; it prunes run rows older than 90 days. - Runner:
runner.tsruns due duties, one at a time per duty, andfire(event)runs the duties waiting on an event. It runs on the autonomy clock after the sentinel. - Probes: a finding or action without a probe is dropped and the run is recorded as
refused. - Bulk actions:
ctx.bulktouches one item, checks its probe, then continues, capped at 20 a run. A failed check stops everything else and recordscanary. - Budget: going over runs per day or dollars per day records
budget, once per day rather than every tick. Going over a run's network-call or time ceiling also recordsbudget. Time is wall-clock, a stand-in for CPU. - Pausing: three errors in a row pause the duty and keep the last error as the reason.
- Filing:
file.tscomments on the open issue for a finding's key, or opens one. - No landing: nothing under
src/maintain/imports merge, push or spawn, andtest/maintain-no-land.test.tschecks that. The duty context also has no merge or push method. - API:
GET /api/v1/maintain/dutiesGET /api/v1/maintain/runs?duty=POST /api/v1/maintain/duties/:name/pausePOST /api/v1/maintain/duties/:name/resume
All four are admin-only, documented in OpenAPI, and covered by
test/maintain-api.test.ts. - Tests: the five named in the issue (
test/maintain-runner.test.ts,maintain-probe-required,maintain-canary,maintain-budget,maintain-no-land) plusmaintain-api. Docs are indocs/features/maintainer.md.
What I left out
- Sentinel and hunters: they are not moved onto the registry. They have their own filing and de-duplication tables, so moving them isn't cheap. That is a follow-up.
- Board page and MCP tool: pause and resume are API-only.
- Filing identity: findings are filed as an agent named
maintainer, or the first admin if there isn't one. I kept the sentinel's fallback, which means a fresh forge files as an admin until amaintaineragent exists. - Dollar budget:
ctx.spendexists but nothing reports spend into it yet, so the dollar budget only bites for duties that call it.
To try it
- Run the tests:
bun test test/maintain-*.test.ts. - Call the API:
curl -H "authorization: Bearer $ADMIN_TOKEN" $FORGE_URL/api/v1/maintain/duties.
🤖 Generated with Claude Code
The failed check was the gate wanting two lines in a commit message. I added them in a new empty commit, and bun scripts/gate.ts now passes locally with no output. I haven't seen the forge's re-run on the push.
Why now:says #7554 gives workers #7555 to #7560 a duty registry to plug into.Try:says to callGET /api/v1/maintain/dutieswith an admin token on the preview, then pause and resumerun-log. The exact calls arePOST /api/v1/maintain/duties/run-log/pauseand.../resume.
No code changed, so the earlier test results still stand.
The type error came from a change on main that my branch didn't have yet. A second Record<CrewRole, string> (the team-list titles, SEAT_TITLE in src/web/studio/crew.ts) had arrived there, and it had no entry for maintainer.
I merged origin/main into the branch and added maintainer: "Maintainers" to that map. Afterwards bun x tsc --noEmit and bun scripts/gate.ts were clean. The maintain, studio and crew-seats tests pass: 54 tests, 0 failures. The fix is pushed as 6cee09ed. I haven't seen the forge's re-run of the check.
Parked by the crew: the check stayed red through 2 automatic tries
This adds the maintainer framework, but the board page for pausing and resuming a duty isn't built; that's API-only for now. I ran the new tests, the OpenAPI/contract tests,
tsc,scripts/gate.ts,scripts/hollow.tsand a few cross files, and all pass. I did not runscripts/design-lint.ts(I touched nosrc/webpage) or the full suite; the forge's check does that on push.What changed
maintaineris now a crew role (src/core/agents.ts). It has an entry in the seat-slot and studio label maps and is not one of the three build/plan/review pillars.maintenance_duty(switch, pause reason, error count),maintenance_run(one row per run: findings, actions, probes, outcome, cost) andmaintenance_finding(finding key to issue). It is pinned.src/maintain/duty.tsandregistry.tsdefine a duty by name, trigger ({every}or{on}), budget and handler. A duty is one file insrc/maintain/duties/plus one line induties/index.ts.run_log.tsis the first one; it prunes run rows older than 90 days.runner.tsruns due duties, one at a time per duty, andfire(event)runs the duties waiting on an event. It runs on the autonomy clock after the sentinel.refused.ctx.bulktouches one item, checks its probe, then continues, capped at 20 a run. A failed check stops everything else and recordscanary.budget, once per day rather than every tick. Going over a run's network-call or time ceiling also recordsbudget. Time is wall-clock, a stand-in for CPU.file.tscomments on the open issue for a finding's key, or opens one.src/maintain/imports merge, push or spawn, andtest/maintain-no-land.test.tschecks that. The duty context also has no merge or push method.GET /api/v1/maintain/dutiesGET /api/v1/maintain/runs?duty=POST /api/v1/maintain/duties/:name/pausePOST /api/v1/maintain/duties/:name/resumeAll four are admin-only, documented in OpenAPI, and covered by
test/maintain-api.test.ts.test/maintain-runner.test.ts,maintain-probe-required,maintain-canary,maintain-budget,maintain-no-land) plusmaintain-api. Docs are indocs/features/maintainer.md.What I left out
maintainer, or the first admin if there isn't one. I kept the sentinel's fallback, which means a fresh forge files as an admin until amaintaineragent exists.ctx.spendexists but nothing reports spend into it yet, so the dollar budget only bites for duties that call it.To try it
bun test test/maintain-*.test.ts.curl -H "authorization: Bearer $ADMIN_TOKEN" $FORGE_URL/api/v1/maintain/duties.🤖 Generated with Claude Code
Closes #7554