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

Parked opened this in answer to
Closed without merging

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.

Notes

stopped parked by the crew deploy 6cee09e

opened this

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: maintainer is 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) and maintenance_finding (finding key to issue). It is pinned.
  • Duty and registry: src/maintain/duty.ts and registry.ts define a duty by name, trigger ({every} or {on}), budget and handler. A duty is one file in src/maintain/duties/ plus one line in duties/index.ts. run_log.ts is the first one; it prunes run rows older than 90 days.
  • Runner: runner.ts runs due duties, one at a time per duty, and fire(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.bulk touches one item, checks its probe, then continues, capped at 20 a run. A failed check stops everything else and records canary.
  • 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 records budget. 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.ts comments on the open issue for a finding's key, or opens one.
  • No landing: nothing under src/maintain/ imports merge, push or spawn, and test/maintain-no-land.test.ts checks that. The duty context also has no merge or push method.
  • API:
    • GET /api/v1/maintain/duties
    • GET /api/v1/maintain/runs?duty=
    • POST /api/v1/maintain/duties/:name/pause
    • POST /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) plus maintain-api. Docs are in docs/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 a maintainer agent exists.
  • Dollar budget: ctx.spend exists 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

Closes #7554

3 earlier comments
commented

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: maintainer is 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) and maintenance_finding (finding key to issue). It is pinned.
  • Duty and registry: src/maintain/duty.ts and registry.ts define a duty by name, trigger ({every} or {on}), budget and handler. A duty is one file in src/maintain/duties/ plus one line in duties/index.ts. run_log.ts is the first one; it prunes run rows older than 90 days.
  • Runner: runner.ts runs due duties, one at a time per duty, and fire(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.bulk touches one item, checks its probe, then continues, capped at 20 a run. A failed check stops everything else and records canary.
  • 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 records budget. 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.ts comments on the open issue for a finding's key, or opens one.
  • No landing: nothing under src/maintain/ imports merge, push or spawn, and test/maintain-no-land.test.ts checks that. The duty context also has no merge or push method.
  • API:
    • GET /api/v1/maintain/duties
    • GET /api/v1/maintain/runs?duty=
    • POST /api/v1/maintain/duties/:name/pause
    • POST /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) plus maintain-api. Docs are in docs/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 a maintainer agent exists.
  • Dollar budget: ctx.spend exists 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

commented

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 call GET /api/v1/maintain/duties with an admin token on the preview, then pause and resume run-log. The exact calls are POST /api/v1/maintain/duties/run-log/pause and .../resume.

No code changed, so the earlier test results still stand.

commented

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.

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs