Skip to content

v0.15.0

Choose a tag to compare

@sdsrss sdsrss released this 20 Sep 10:12
· 72 commits to main since this release

Everything the 2026-09-20 production-readiness audit rated P0 or P1, fixed with
a reproduction first and a failing assertion before each change. Suite 477 → 600
assertions across 13 suites (a new tests/test-harness.sh); the six
bash-3.2-floor suites re-verified under a real 3.2.57. Minor, not patch: several
user-visible defaults change below.

Upgrade note — read this if you schedule the unattended drivers.

  • Two timers on one repo at the same minute is now refused at install time.
    Both modes default to --time 03:00, and the drivers cannot share a working
    tree. If you run both timers against one repo today, install-timer.sh will
    refuse the next re-install of the second one. Action: re-run it with a
    different time (--time 04:00). Nothing breaks until you re-install; existing
    units keep running, and from this version the loser simply exits 69 instead of
    editing the tree underneath the winner.
  • Two new exit codes. 69 (EX_UNAVAILABLE) = another driver holds the
    repo lock; 143 = the driver was signalled and terminated its session.
    Deliberately distinct from the 75 these drivers use for provider limits.
    Action: if you alert on non-zero exits, decide which of these are noise.
  • A failure is no longer reported as a provider limit just because the code it
    was working on mentions one.
    Runs that used to exit 75 ("try again later")
    now surface their real exit code, and 124 is reported as the timeout it is.
    Action: monitoring that keyed on 75 will start seeing the true failures it
    was masking.
  • unattended-polish.sh sessions are now actually killed at the budget
    (timeout -k 30, which its autoloop sibling always had). A session that
    ignores SIGTERM no longer runs past LOOP_ENG_MAX_MINUTES.
  • Contributors: tests/test-manifest.sh and tests/test-hooks-json.sh now
    FAIL on a host with no python3/jq instead of reporting 0 passed, 0 failed and exiting 0. Action: install either one. CI has both on all legs.

Revert path: pin 0.14.0 in your marketplace entry. Every new behavior above is
in the drivers, the installer or the test harness — no .loop/ on-disk format
changed, so moving between the two versions needs no migration.

Live-install smoke: PASS (Claude Code 2.1.278, headless, throwaway
CLAUDE_CONFIG_DIR, GitHub-source marketplace install of this release's own
content on main — so no source-type disclosure is owed). Each step asserted on
state the mechanism writes, with the live cache copies instrumented so the
verdicts are machine facts rather than model reports:

  • evidence-gate: the instrumented deny() fired (EGDENY: raw evidence under .loop/evidence/), the file was not created, and the denial names the real
    absolute runner path under plugins/cache/.../0.15.0/ rather than the
    <loop-eng plugin root> placeholder — so hooks.json auto-loaded and
    CLAUDE_PLUGIN_ROOT reaches hook processes.
  • arm-contract: armed from …/plugins/cache/loop-eng/loop-eng/0.15.0/…, the
    version-pinned copy that enforces, not the plugins/marketplaces/ clone.
  • stop-gate: exactly three SGBLOCK markers (= MAX_BLOCKS) on a red
    contract, and .loop/results.json machine-written by run-contract.sh with
    "all_green": false.
  • ${CLAUDE_PLUGIN_ROOT} in command bodies: /loop-eng:autoloop armed,
    reached ALL GREEN in cycle 1/5, lifted the gate itself, and left a two-criteria
    ledger with "all_green": true.

One observation worth keeping, and the reason the dispatch guidance above was
rewritten rather than deleted: on this run both subagent dispatches detached to
the background
despite the synchronous request, costing two extra turns and
producing one duplicate (read-only) checker dispatch. The 0.14.0 smoke saw
synchronous dispatch on this same CLI version, so it is not a stable property.
It did not produce a false green — the ledger stayed machine-written throughout,
which is the guarantee that does not depend on dispatch semantics.

Test blind spot: a safety default could be deleted and the suite stayed
green.
Both unattended drivers hand claude an argv that is their entire
contract with the session, and the stub in each suite ignored it. Measured, not
argued: deleting $MODE from unattended-polish.sh's -p "/polish $SCOPE $MODE" — so every scheduled run auto-fixes the repo under bypassPermissions
instead of reporting — kept tests/test-unattended-polish.sh at 39 passed / 0
failed. Swapping /autoloop for /polish and bypassPermissions for default
in unattended-autoloop.sh kept its suite at 41 passed / 0 failed. report-only
is that driver's only write protection, and nothing was watching it.

Both stubs now record their full argv (STUB_ARGV_LOG, one argument per line)
and each suite asserts what actually goes out: the command, the scope, the
report-only default and its removal only under the two-key --auto-fix +
LOOP_ENG_ALLOW_AUTOFIX=1 opt-in, --permission-mode bypassPermissions, and
the per-driver turn cap (120 / 150). Each refusal path is asserted to invoke no
session at all, rather than merely to exit non-zero. Suite 477 → 490 assertions;
the two mutations above now fail 1 and 2 assertions respectively.

No runtime script changed here — this is the gate that was missing, not a
behavior fix.

A suite that ran no assertions is no longer reported green.
tests/test-manifest.sh needs python3 and tests/test-hooks-json.sh needs
jq or python3; on a host with neither, each printed 0 passed, 0 failed,
exited 0, and run-all.sh printed ALL GREEN for a run that checked nothing
about the two manifests or about hooks.json. Reproduced with a PATH holding
neither parser. lib.sh's report() now fails when PASS and FAIL are both
zero, and the new tests/test-harness.sh pins that contract — including that an
all-red suite (PASS=0, FAIL>0) still fails for the ordinary reason — plus
the consequence itself: both parser-dependent suites are run under that
restricted PATH and asserted to exit non-zero. Upgrade note for contributors:
on a box without python3/jq those two suites now go red instead of quietly
passing. Install either one; CI already has both on all three legs.

The stop-gate's green path clears three files, and only one was watched.
Removing "$SHA_LOCK" and "$COUNT_FILE" from hooks/stop-gate.sh's green
rm kept tests/test-stop-gate.sh at 33 passed / 0 failed. Both leftovers bite
the next loop: a stale criteria.sha256 locks a contract that no longer
exists, so the next arm's criteria.tsv fails the hash check and every stop
after it exits 77 "tampered"; a stale gate-count starts that loop partway to
the 3-block ceiling. The green-path test now arms both files first — the first
draft asserted their absence over files the setup had already deleted, so it
passed against the very mutation it was written to catch — and asserts all three
are gone. Suite 490 → 504 assertions across 13 suites.

A criterion could delete the criteria that came after it, and the ledger said
ALL GREEN.
run-contract.sh streamed criteria.tsv with while … done < "$CRIT", so a criterion that truncated or rewrote that file made every line
after it vanish mid-read — silently, at EOF. Not "skipped", not "malformed":
absent.

printf 'one\ttruncates\t: > .loop/criteria.tsv; true\ntwo\tred\tfalse\n' > .loop/criteria.tsv
→ exit 0, results.json holds only "one", "all_green": true

The authored contract's second criterion was false. Neither the vacuous guard
nor the partial-parse guard can see this, because from their side the contract
simply was one line — which makes it the one gap in "passes: true can only
come from running the command".

Two halves, mirroring the two questions a ledger has to answer. What ran:
the criteria loop now reads a private snapshot taken after the hash check, so
the executed set is the set that was read and (when armed) hash-verified,
whatever the commands do to the file afterwards; an appended criterion is not
executed by the run that appended it. Whether the result may be reported:
when the loop is armed with a hash-lock, criteria.tsv is re-hashed after the
last criterion and a mismatch writes a tampered ledger and exits 77. That
post-run check is gated on "a lock was checked at start", not on the lock still
existing, so deleting criteria.sha256 mid-run is not a bypass.

run-contract.sh now needs cp alongside the mv/rm/mkdir/cut/date/
tail/sed it already required; both restricted-PATH fixtures list it. Suite
504 → 517 assertions; 9 of the 13 new ones fail against the pre-fix runner.

A criterion with an empty description bricked the loop that armed it.
id<TAB><TAB>cmd is three real TAB-separated columns with a blank middle one.
IFS=$'\t' read -r id desc cmd looks like the right spelling and is wrong in
one silent way: TAB is IFS whitespace, so bash collapses runs of it — the line
came back as desc=cmd, cmd="", i.e. malformed.

arm-contract.sh carried four different splits of that same line: two
awk -F'\t' (which does not collapse) and two IFS=$'\t' read (which does).
They disagreed here and only here. The awk pair called the line runnable, so
arming warned about nothing and pinned the hash; the two read loops saw an empty
command and skipped it, so neither the static parse check nor the red-check ever
looked at it; and run-contract.sh, reading it the collapsing way, called it
malformed and failed closed on every stop — with a message blaming SPACES in
a file that contains none. The evidence-gate had locked criteria.tsv by then,
so the loop could only end by hitting a stop rule.

Both scripts now split on the first two TABs: everything after the second is
the command, an empty description is legal, and fewer than two TABs / an empty
id / an empty command is malformed. Five parse sites became two (one per
script). Both malformed messages now state that rule instead of asserting a
cause the runner cannot observe. Verified under real bash 3.2.57 (the CI floor)
as well as 5.x. Suite 517 → 533 assertions; 7 of the new ones fail against the
pre-fix scripts.

Killing an unattended driver left its claude session running. Neither
driver had a trap (grep -c trap was 0 in both) and GNU timeout places
itself in its own process group, so systemctl stop on a host whose unit does
not cgroup-kill, a cron kill <pid>, or a hand-typed Ctrl-C killed the driver
and orphaned a --permission-mode bypassPermissions session — for
unattended-autoloop.sh, one that writes code — to run on to its own budget
with nobody watching it. Reproduced with a sleeping stub: driver dead, stub
alive.

Each session now runs in the background under an explicit wait (a foreground
child blocks trap dispatch, so a trap around one fires too late to act), with a
TERM INT HUP handler that TERMs the session, waits up to 10s, then KILLs it,
logs the interruption — with the pending-item count, for autoloop — and exits
143 (128+SIGTERM) so a scheduler can tell an interrupted run from a failed
one.

unattended-polish.sh gets the -k 30 its sibling always had. Plain
timeout sends TERM and then waits indefinitely if the child ignores it, so a
wedged session made LOOP_ENG_MAX_MINUTES advisory rather than a budget.

Suite 533 → 542 assertions; the orphan and kill-after assertions fail against
the pre-fix drivers.

Two drivers could edit one working tree at the same time. Nothing enforced
mutual exclusion: both passed the dirty-tree check (the tree is clean at that
instant) and both started a bypassPermissions session. Reproduced with two
concurrent drivers: 2 sessions started. install-timer.sh defaults both
modes to --time 03:00, so installing a polish timer and an autoloop timer on
one repo is the documented route to it.

Each driver now takes a lock in .loop/ before starting a session: flock
where the host has it (the kernel releases it however the process dies), an
atomic mkdir with a pid-staleness check where it does not (stock macOS ships
no flock(1); a driver killed with SIGKILL runs no trap, so the pid inside the
lock is what tells "held" from "abandoned"). The second driver exits 69
(EX_UNAVAILABLE) and says so in the rolling log — deliberately not the 75
these drivers already use for provider limits, so a scheduler alerting on 75
does not start alerting about its own second timer.

Upgrade note — install-timer.sh now refuses a same-repo, same-minute
collision.
With the lock in place the tree is safe, but the collision becomes
silent: the losing timer does no work, every night, while systemctl status
stays green. Installing the second mode on a repo whose other timer already
runs at that exact time is therefore refused, naming --time and the
uninstall-timer.sh command as the two ways out. If you have both timers on one
repo at 03:00 today, re-run the installer for one of them with a different
--time. Two different repos at 03:00, and the same repo at different
times, are both still allowed — the latter is how you run both.

Two stop rules could stop a loop that was working, and a third could stop it
after one backlog item.
These live only in Markdown, so nothing caught the
contradictions.

Stop rule 3 fired on a repeated failure, while loop-builder.md tells the
builder to fix exactly ONE root cause per round. A criterion with two
independent causes behind it is still red after the first is fixed — the failure
repeats while the work progresses — so the loop stopped saying "the builder is
guessing" about a builder that was not. "Same failure" also had no definition:
file:line moves with every edit above it, so the same defect reads as a new
failure and two defects at one line read as one. The rule now keys on the
builder's Root cause: line, a new required field in its report; the checker
prefixes each failure with the contract criterion id it came from, and
identifies failures within a criterion by the normalized assertion line.

Stop rule 5 counted the checker's failure list, which loop-checker.md
instructs to merge per file — so the count tracked how defects were distributed
across files, not how many there were. It now counts RED criteria in
.loop/results.json, which is machine-written and unmerged.

Step 3 said "if the checker reports ALL GREEN: stop", while the multi-item
section says the checker judges only the current round's item and lists the rest
as EXPECTED-RED. Read literally, round 1 of a five-item backlog ended the loop
and printed a wrap-up diff. It now ticks the item and moves to the next, and
finishes only when no - [ ] line remains. The round budget said four different
things across the file; it is now stated once: 5 rounds is the total for the
invocation, one item may take several, and the counter does not reset at item
boundaries
(stop rules 3 and 5 still do).

The synchronous-dispatch mitigation named a parameter that does not exist.
The prompt told the orchestrator to set run_in_background: false; the Agent
tool has no such input, so the instruction could not be carried out. It now
describes the dispatch shape the orchestrator actually controls — one subagent
per dispatch, awaited before anything else, no fan-out — states the cost when a
harness backgrounds them anyway (two dispatches per round against a 3-block
ceiling reaches it inside round 2, exiting with the gate still armed), and cites
the one harness where it was measured to be synchronous (CLI 2.1.278, the 0.14.0
smoke). Deliberately not fixed by teaching the stop-gate to skip blocks while
a marker file exists: that marker would be prompt-writable, and a bypass the
model can create is not a mechanism.

Nine grep assertions in tests/test-packaging.sh now pin these decisions — they
cannot prove a prompt works, only that these specific contradictions stay fixed.

Three ordinary ways of typing a write slipped past the evidence-gate's Bash
pattern.
None is an evasion: rm -rf .loop/evidence (the trailing slash was
required, so the plain directory name — how anyone writes an rm — matched
nothing), echo x >| .loop/results.json (>| is the noclobber override, and
the verb group stopped at >>?), and echo x > .loop//results.json (a doubled
slash is the same path to every OS). All three are denied now, and the
evidence-directory name matches when followed by /, by end of line, or by
anything that cannot be part of a filename — deliberately not \b, which
counts - and . as boundaries and would newly deny .loop/evidence-notes.md
and .loop/evidence.bak, siblings that are not the ledger. Unchanged and still
stated in the header: indirection that hides the path from the command text
(F=.loop/results.json; echo x > $F) is out of scope for any regex; the
guarantee for that class is run-contract's hash re-derivation.

A failure was reported as a provider limit whenever the code under review
mentioned one.
"The grep only runs on failed runs, which bounds the
false-positive surface" was the stated reasoning, and it does not hold: a polish
session reviews code, so its log is full of the text under review. A stub
printing checkQuota() { /* the quota is never reset */ } and exiting 2 came
back as EX_TEMPFAIL 75 — "try again later" — and the real failure never
reached whatever watches exit codes. In the autoloop driver the same match also
parks the run in sleep $((LIMIT_WAIT_MIN * 60)): at the default, a full hour
of doing nothing before retrying a failure that will not fix itself.

Both drivers now match provider phrases (usage limit reached, quota exceeded, rate limit exceeded, rate_limit_error, overloaded_error, too many requests) in the last 40 lines of the log — a limit ends the run, so it is
the last thing written, while the body is the material under review — and never
on exit 124, which is our own wall-clock kill. 0.14.0's release notes recorded
that last case as a known consequence of enforcing the cap on macOS; it is fixed
here.

A killed session left the gate armed, and that bricked every session after
it.
.loop/active is lifted by the stop-gate only when the contract goes
green; a session killed by the driver's own timeout, by a TERM, or by the
3-block ceiling leaves the file on disk with a clean tree. The next session then
tries to write its own criteria.tsv and the evidence-gate denies it — through
Write and through Bash, because that file is the armed contract — so it arms
nothing, verifies nothing, commits nothing. Two of those and the circuit breaker
opens, with only NO new commits in the log to explain a backlog that stopped
moving. Reproduced: DENIED on both write paths, then circuit breaker OPEN.

unattended-autoloop.sh now reclaims the leftover before its first session and
again after every session — after, because that is where a killed session's
leftover actually appears, and deferring it to the next driver run would cost
this run every remaining session. All three files go (active, gate-count,
criteria.sha256): a lone hash-lock makes the next arm's own criteria.tsv
read as tampered, a lone counter starts that loop partway to the ceiling. The
driver is the human-authorized outer layer — "the model must not disarm its own
gate" governs the session inside, not the scheduler that started it — so this is
its job, and doing it from the prompt would not be equivalent.
commands/autoloop.md Step 0 and README's resume bullet carry the manual form,
including the two-call ordering the evidence-gate requires.

.loop/ had to be gitignored for anything to work, and nothing made it so.
README asserted the directory "is gitignored"; this repo's own .gitignore,
tests/lib.sh and RELEASING.md each hand-write the line, so the assumption
was known — the Install instructions just never stated it. In a project without
it, the builder's git add -A commits criteria.tsv, criteria.sha256,
results.json and evidence/; the stop-gate then rewrites results.json on
every stop, the tree is permanently M .loop/results.json, and both unattended
drivers refuse to run ("dirty tree, refusing") from then on. Verified end to
end: five .loop files committed, then a wedged tree.

arm-contract.sh now checks at the start of every loop. Not ignored → the
directory is appended to .git/info/exclude, which is local and untracked, so
arming a loop never turns into a diff in someone's PR (idempotent: a second arm
appends nothing). Already tracked → no ignore rule can undo that, so it
warns and prints the git rm -r --cached command that does, and still arms —
stranding a loop over bookkeeping would be the worse trade. commands/autoloop.md
Step 0 checks git ls-files .loop for the tracked case, and README's loop-state
bullet now describes the guarantee instead of asserting the outcome.

Suite 542 → 600 assertions. Three pre-existing install-timer fixtures that
happened to stack both modes on one repo at 03:00 now pass --time 04:00;
they were testing uninstall symmetry and unit contents, not collisions.