Verbs

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:

  1. Plans worktree_gc, branch_gc, and sandbox_checkpoint_gc (dry run — nothing is touched; the checkpoint plan classifies the stale agentproto-checkpoint/* refs a dead sandbox left on the remote as safe / keep / unknown).
  2. 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 via branch_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 configured profile and route ride the spawn too (access.profileRef / route), so an opencode-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. Otherwise worktree gc and branch gc would each hold them forever. The report lists each such worktree's verdict, plus the agentproto worktree rm command when the reviewer agreed nothing of value is lost. Removal stays manual. The workflow input reviewHeldWorktrees: false turns this off.
  3. Re-plans branch_gc to confirm every candidate got a verdict, and reports any gap, the verdict tally, and the salvage branches by name.
  4. With --apply-merged: applies branch_gc (reclaim-class only by default), worktree_gc, and sandbox_checkpoint_gc (stale checkpoint refs; the engine re-plans and re-classifies every ref immediately before deleting it). Adding --apply-reviewed runs the branch apply with includeReviewed: true, so a review-class branch whose stored verdict agreed for the same tip is reclaimed too. branch_gc still 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, version or packageManager pin 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 example uncovered 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-guard turns 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, unknown only when the forge gave no answer) and the reviewer's one-line reason. Below the rows is ONE agentproto 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 (see branch 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, a review-class branch is never reclaimed.
  5. 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.

FlagDefaultDescription
--repo <dir>cwdAny dir inside the repo. Repeatable — pass multiple --repo flags to target specific repos. Combined with --all to supplement discovered repos.
--allfalseRun 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>noneWith --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-mergedfalseApply (reclaim-class only) after review. When used with --all, applies to every repo.
--apply-reviewedfalseWith --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-guardfalseWorkflow 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 modelRolePresetReviewer 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.
--waitfalseBlock until each run ends, then print its markdown report. Exit 0 when all done, 1 when any failed or was cancelled.
--jsonfalsePrint 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 --wait

Scheduling 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.