agentproto maintain
agentproto maintain [--repo <dir>]... [--all] [--apply-merged] [--apply-reviewed] [--review-preset <name>] [--max-reviews <n>] [--worktrees-root <dir>]... [--wait] [--json]Convenience shortcut over agentproto workflow run-file for the built-in
repo-maintenance app's
maintain workflow. Needs a running daemon (agentproto serve) — unlike
branch gc and worktree gc, the workflow's
review step spawns real agent sessions.
One run:
- Plans
worktree_gc,branch_gc, andsandbox_checkpoint_gc(dry run — nothing is touched; the checkpoint plan classifies the staleagentproto-checkpoint/*refs a dead sandbox left on the remote as safe / keep / unknown). - Fans a reviewer agent out over the unmerged branch candidates with no
stored verdict yet — at most
maxReviews(--max-reviews, default 40) per run, newest tip first, so daily runs walk a large backlog — one turn per unique tip sha: a small model when the candidate's residual is 3 files or fewer, a large model otherwise. Each turn records a verdict viabranch_gc_verdict— recording a verdict never deletes anything. A turn that ends without a stored verdict gets one same-session re-prompt, then one large-model retry. A reviewer model role's configuredprofileandrouteride the spawn too (access.profileRef/route), so anopencode-go/...reviewer can bill a named profile instead of ambient auth. Branches held only because they're checked out in a linked worktree join the queue too, when that worktree is idle (no live session), clean, has no open PR, and its tip is at least 3 days old. Otherwiseworktree gcandbranch gcwould each hold them forever. The report lists each such worktree's verdict, plus theagentproto worktree rmcommand when the reviewer agreed nothing of value is lost. Removal stays manual. The workflow inputreviewHeldWorktrees: falseturns this off. - Re-plans
branch_gcto confirm every candidate got a verdict, and reports any gap, the verdict tally, and thesalvagebranches by name. - With
--apply-merged: appliesbranch_gc(reclaim-class only by default),worktree_gc, andsandbox_checkpoint_gc(stale checkpoint refs; the engine re-plans and re-classifies every ref immediately before deleting it). Adding--apply-reviewedruns the branch apply withincludeReviewed: true, so areview-class branch whose stored verdict agreed for the same tip is reclaimed too.branch_gcstill enforces its deterministic line-coverage guard (default 95%): an approval below it is refused (refused-guard) unless the verified-pr pass proves it (a superseded verdict whose cited PR the forge confirms merged into base, with every uncovered file explained by that PR, a changeset, a later move on base or the dep-bump per-file rules), or the dep-bump pass does (every added line is a lockfile, changeset, dependency spec,versionorpackageManagerpin base already has at least as new), or the history-covered pass does (every line missing from base's tip was once added to the same path in base's history, and nothing base still has is deleted). Tips that pass are listed in "Auto-passed by verified-pr" (branch, PR, why, for exampleuncovered files: 1 touched by #2143, 1 manifest-proven), "Auto-passed by dep-bump" (branch, lines checked) and "Auto-passed by history-covered" (branch, lines found, base commits);--require-operator-below-guardturns all three passes off. The rest are listed in the report's "Human decision queue", each row ending with the reason the pass refused it. That queue is never capped: every refused tip is listed once (a branch and its remote twin share one line, with the ref kinds and the sha), lowest coverage first, each row with its line coverage, stored verdict, PR state (by head branch name from the forge's bulk PR lists,unknownonly when the forge gave no answer) and the reviewer's one-line reason. Below the rows is ONEagentproto branch gc approve <sha>... --by <your name>command covering every queued tip, one sha per line with the flags last, so deleting a line drops that tip (seebranch gc approve). Other lists in the report stop at 20 names and say where the full list is in the run output. Without--apply-reviewed, areview-class branch is never reclaimed. - Reports a markdown summary.
Verdicts are recorded with branch_gc_verdict. A reviewer verdict under the
line-coverage guard is refused by branch_gc; an operator approval for the
same tip sha (agentproto branch gc approve, which copies the stored verdict
and adds an operator: { by, note? } block) is
the human exit from that queue and lets includeReviewed reclaim it despite
the guard (the plan shows verdictGuard: bypassed by operator <by>). The
maintain workflow applies with includeReviewed: $input.applyReviewed —
false unless --apply-reviewed is passed (with --apply-merged), so by
default it records and reports verdicts but never deletes a review-class
branch.
| Flag | Default | Description |
|---|---|---|
--repo <dir> | cwd | Any dir inside the repo. Repeatable — pass multiple --repo flags to target specific repos. Combined with --all to supplement discovered repos. |
--all | false | Run once per repo: every main repo that owns a worktree under the worktrees root, plus any --repo dirs. Prints the discovered repo list first; exits 1 if any run fails. |
--worktrees-root <dir> | none | With --all: also scan this dir for worktrees, in addition to the configured worktrees root. Repeatable. A dir holds worktrees directly (<dir>/<slug>) or in buckets (<dir>/<repo>/<slug>); main checkouts inside it are skipped. Use it for pools outside the root (e.g. a repo's _worktrees/), or set them once in config worktrees.extraRoots; the flag adds to that list. |
--apply-merged | false | Apply (reclaim-class only) after review. When used with --all, applies to every repo. |
--apply-reviewed | false | With --apply-merged, also reclaim review-class branches whose stored verdict agreed (includeReviewed: true). branch_gc refuses approvals below its line-coverage guard (default 95%) unless its verified-pr pass proves them, and reports them; ignored without --apply-merged. |
--require-operator-below-guard | false | Workflow input requireOperatorBelowGuard: turn the verified-pr, dep-bump and history-covered passes off, so below the guard only an operator approval reclaims. |
--review-preset <name> | daemon modelRolePreset | Reviewer model set for this run: opus, sonnet, haiku, go-free, free-sonnet (see modelRolePreset). Each reviewer spawns on the adapter its model needs, so go-free runs on opencode. |
--max-reviews <n> | workflow maxReviews (40) | Cap how many unmerged branches this run sends to a reviewer (newest tip first). Must be a positive integer, else exit 2 before any daemon contact. Branches with a stored verdict are never re-reviewed, so repeated runs walk the backlog. |
--wait | false | Block until each run ends, then print its markdown report. Exit 0 when all done, 1 when any failed or was cancelled. |
--json | false | Print the raw workflow_run_file reply (with --wait: the finished run records, one per repo). |
This starts the run and returns immediately (the run executes in the background) — poll it with:
agentproto workflow status <runId>Or pass --wait to block until it finishes and print the report inline.
Examples
# Plan + review only, nothing deleted
agentproto maintain --repo ~/code/my-app
# Plan + review, then apply reclaim-class branch/worktree gc
agentproto maintain --repo ~/code/my-app --apply-merged
# Also apply agreed reviewed branches (line-coverage guard still applies)
agentproto maintain --repo ~/code/my-app --apply-merged --apply-reviewed
# Run for every repo that owns worktrees under the worktrees root
agentproto maintain --all --apply-merged
# Block until done and print the report
agentproto maintain --repo ~/code/my-app --waitScheduling it
packages/apps/repo-maintenance/routines/ ships two AIP-41 ROUTINE.md
templates targeting the same maintain workflow, both enabled: false:
repo-maintenance-daily (plan + review, no apply) and
repo-maintenance-weekly (applyMerged: true + applyReviewed: true; drop
applyReviewed to keep the weekly apply reclaim-class only). See that
directory's README for how to enable one per workspace.