Repository navigation
v0.8.0
A timer run and an interactive session can see each other through leases, a pull
request stalled on mechanical review items can be finished by a script, and
every tunable has one default that the docs are checked against.
Added
-
maintainer stalledandmaintainer-repo fixup: finish a pull request the
author left on mechanical review items. Contributor pull requests sat on
CHANGES_REQUESTED for days when all that remained was a rebase, a test count
that moved under them or one doc line, and the doctrine forbade touching their
branch (story 15). The review prompts now end every CHANGES_REQUESTED body with
a hiddenfixup-itemsmarker naming the head and a closed list of kinds
(rebase,test-count,doc-line).stalledlists the pull requests whose
maintainer review carries one for the current head, with no author commit,
comment, review or thread reply since, older thanFIXUP_QUIET_DAYS(10).
fixupposts one heads-up, waitsFIXUP_NOTICE_DAYS(5), then works in a
scratch clone with no hook run: it rebases or applies a patch the run wrote
(capped atFIXUP_MAX_LINES, 20; never production,.github/or anything the
screen calls executable; a test count must match the profile's own
FIXUP_COUNT_CMD), commits as the maintainer with aCo-authored-bytrailer
for the author, pushes with--force-with-leaseagainst the checked head when
it rewrites, and reads the head back before it says it worked. Substantive
items, conflicts,maintainerCanModify=false, bots,action_requiredruns and
any author activity are refused in code, and--dry-runandPOST=offpush
nothing. The write happens in the script, never through the model. Story 15 is
no longer a gap. Newmaintainer fixup-check <pr>prints the check the script
runs. -
maintainer lease: say who is working a pull request. A timer run and an
interactive session worked #637, #658 and #660 at the same time on 2026-10-25
(docs/lessons.md 8 and 80 are the same fault), and the run's report could not
tell whose review it had found.lease take <pr>... [--ttl D] [--for TEXT]
writes a small file underleases/naming the holder, the note, and when it
expires;takerefuses another holder's live lease and names them, renews
its own, and prints a takeover of an expired one;check <pr>exits 0 free or
yours, 1 held, 2 unreadable (never free);release <pr>...frees yours. The
read-decide-write step runs under a short flock, so of two simultaneous takes
exactly one wins. New defaultLEASE_TTL_SECONDS(3600). -
A run says it is running.
run.shwritesleases/run.json(task, pid, run
id) right after it takesrun.lockand removes it on every exit, through an
internalmaintainer run-leaseverb. Liveness is never read from the file or
a pid:maintainer statusasks the lock, so a file left by a killed run
beside a free lock prints as stale and is ignored.statusgains aleases
block (the run, then each PR lease with holder, note, renewed-ago and
expires-in; expired ones marked and ignored). An interactivelease take
while a run is live warns with the run id andmaintainer abort, and still
takes: runs yield to interactive work. -
gcprunes old leases and the doctor flags forgotten ones.maintainer gcremoves a PR lease that expired longer ago thanRETENTION_DAYS, never a
live one, the run lease, or a file it cannot read.maintainer-doctorwarns
about a lease last renewed more thanDOCTOR_LEASE_HOURSago (new default,
12), naming the PRs and thelease releasecommand; an unreadable lease is a
warning, never a pass. -
maintainer-mergeand the review prompts honour leases.verify,
verify-depsandmergeaskmaintainer lease checkfirst and refuse a PR
another actor holds, naming the holder; a lease they cannot read, or no helper
to ask, refuses too. The preamble and the review prompts tell a run to check
the lease before posting and to skip a leased PR in its report. The lease
verbs need only a state directory, so when the caller names one (as
maintainer-mergedoes) they answer with several profiles deployed and none
chosen; without one they still refuse to guess a project. -
maintainer reviewed <pr>. Lists the reviews and inline comments by the
profile's account whosecommit_idis the PR's head now, plus the lease. A
pure read, derived from GitHub on every call; a read that fails refuses
instead of reporting none. The review prompts use it instead of a hand-built
activity loop. docs/maintainer-doctrine.md gains "Who yields to whom". -
lib/defaults.env: one home for every tunable. Defaults were literals
scattered throughbin/andlib/, some written twice (container memory in
twopodman runcalls, the stale window in the code and in a prompt). Each
now has one value and one comment, read by bash through
maintainer_load_defaultsand by the python tools through_tunable().
Precedence isMAINTAINER_<KEY>in the environment, then a suite's own
declaration (suite_memory,suite_cpus,suite_pids,suite_tmpfs), then
profile.env, then the default. New keys:VERIFY_MEMORY,VERIFY_CPUS,
VERIFY_PIDS,VERIFY_TMPFS,VERIFY_TIMEOUT,PREFETCH_TIMEOUT,
MCP_VERIFY_SLACK,STALE_HOLD_DAYS,GH_LIST_LIMIT,CONTRIBUTOR_WINDOW,
GH_TRIES,GH_BACKOFF,DOCTOR_RUN_LIMIT,DENY_WALL_MIN_RULES,
OPENCODE_MODEL;LOCK_WAIT,RETENTION_DAYS,CLAIM_STALE_DAYSand
RED_GRACE_HOURSmoved in. See docs/configuration.md. -
maintainerrefuses a listing that fills its limit. gh cuts a list
silently at--limit, so a roster past the limit lost its tail and read as
"nobody else is available" or "no duplicate".claims,offers,holders,
file-issueand the run snapshot now ask forGH_LIST_LIMITrows (1000) and
stop, namingMAINTAINER_GH_LIST_LIMIT, when a listing comes back exactly
that long. The merged-PR contributor scan stays a window. -
scripts/check_drift.pyholds the documentation to the code. Seven
checks, each proved by planting its defect in a copy of the tree: every verb
the code dispatches is in--helpand indocs/cli.md(the command table
for what a person types, theCalled by run.shsection for the rest), every
key inlib/defaults.envhas a row indocs/configuration.mdwith the same
default, everyMAINTAINER_*name the code reads is documented, every
docs/*.mdpath a message names exists, the README's backend count and the
lesson counts in the README, CONTRIBUTING and the book agree with the tree,
the README's Posts column matches eachprofile.env, and every CHANGELOG
version has a link at the foot. The pre-commit hook, CI and the test suite
run it.
Fixed
-
A quiet run's report is no longer refused for doing what the preamble asked (#133).
The preamble asked for a two-line report andfinishrefused anything under three,
so 12 of 32 magent runs from 2026-10-02 to 2026-10-25 were indexedABORTED, no report
with their report inruns/.REPORT_MIN_LINESinlib/defaults.envis now the one
number, and the suite fails when the preamble disagrees with it. A report thatfinish
refuses is now indexed and alerted asreport refused by finish, with the reason, not
as a missing report. Lessons 111 to 113. -
A cancelled check no longer passes the merge gate.
maintainer-merge merge
counted failing and pending checks and ignored the other bucketsghreports,
and never compared what it accepted with the total, so a cancelled check, a
bucket it did not recognise and an empty check list ([]) all read as a green
board. It now refuses unless every check ispassorskippingand at least
one passed, and names the count (2 of 3 checks are pass or skipping). No
test had ever fed it a pending or cancelled bucket; there are nine cases now,
each proved by removing its refusal. -
The documentation matches the code again. The README said three backends
(four exist), "twenty-five" lessons beside 110, and describedmagentas
running atPOST=offwhile its profile posts; the book called lessons
"thirty-six defects" and CONTRIBUTING "forty-one".docs/verifying.mdand
docs/release.md, named in five places in the code, did not exist: both are written.
docs/cli.mddescribedmaintainer logas the run's log (it prints the run
index), omittedrun --show-prompt,verify-deps,verify-partand the
[suite]argument, and the CHANGELOG's links stopped at 0.4.1. Twenty-odd
environment variables the code reads were documented nowhere; they are in
docs/configuration.md. -
maintainer --helplists every verb and works with no profile chosen. The
docstring listed seven of twenty-two verbs, and--helpwas not handled: it
printed to stderr with exit 1, and with two profiles deployed it died in
profile resolution before it printed anything.bin/maintainernow dispatches
through one table (COMMANDS),--help,-handhelpprint it to stdout
and exit 0, and a wrong argument count prints that verb's usage. The test
suite reads the verb list from the same table.maintainer-merge's header now
lists its six verbs, not three.
Changed
- No tool guesses which project it acts on.
maintainer runread
MAINTAINER_PROFILEitself withsysknifeas the fallback, so with one other
profile deployed it started the wrong repository's run; it now uses the
profile resolved once at import, and a machine with none refuses. A profile
that declares noTASKSruns nothing instead of inheriting four task names.
install-launchd.sh,install-cron.shandInstall-Maintainer.ps1require
the profile name (install.sh --uninstallnow strips each deployed profile's
cron block by name, where it used to strip only the default's). The sysknife
review prompt names the profile's own checkout ($MAINTAINER_REPO) instead of
a path on the author's laptop.
scripts/check_drift.py --only repo-namesholds the README claim that no
executable line inbin/orlib/names a project; the test suite runs it. - The sysknife rust suite verifies in 6g, not 2g. 2g OOM-killed rustc twice
on 2026-10-25, in an interactive verify and in the 21:14 timer run, which had
to retry withMAINTAINER_CARGO_JOBS=2. The suite declaressuite_memory
(6g) besidesuite_jobs(4), and a test fails when memory in gigabytes is
below the job count. Other suites keep the 2g default. - The MCP
maintainer_verifydeadline is derived, not 2400 s. 2400 is
shorter than a legitimate verify (clean run, mutated run and dependency fetch
can use 1800 + 1800 + 900). It is now2 x VERIFY_TIMEOUT + PREFETCH_TIMEOUT + MCP_VERIFY_SLACK. CLAIM_STALE_DAYSisMAINTAINER_CLAIM_STALE_DAYSin the environment,
like every other key. The unprefixed spelling was read by one command and
documented nowhere.LOCK_WAITandRETENTION_DAYSare no longer copied into every
profile.env. A profile that declares nothing gets the default. A test
fails ifLOCK_WAITreaches the systemd unit'sTimeoutStartSec, because a
run waiting for the lock spends that budget and would be killed first.