The coursework archive carries third-party content that the cap would
otherwise demand be split: the ASP.NET scaffolder's jQuery/Bootstrap dist
bundle (30,875 lines of JS, 43,027 of CSS -- ~98% of all JS and CSS in that
repo), stock Unity package/template assets, manufacturer-supplied Altium and
PADS component libraries, and the EOPSY course simulators.
The EOPSY entries are the load-bearing ones, because "provided by the
department" is normally a judgement call. It is not here: work/ is the
extraction target of `make setup`, and extracting the committed tarballs and
diffing shows 14/14 java files byte-identical to the originals --
ControlPanel.java (1852 lines) and Kernel.java (511) included. Nothing under
work/ is student-written, so splitting it would diverge the source from the
assignment it shipped with.
A data change to the existing extension point, so md_naming inherits it via
the shared file_length._tables import. The authoritative per-entry reasons
live in gates/vendored.txt in that repo; this tuple mirrors it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0172dj34FDpao6wsix8ZuCzE
`pinned:` is a required field precisely because an entry is an argument about
ONE version. Matching on the package name alone turns a narrow, reasoned hold
into a blanket exemption -- the fleet-wide typescript entry pins 6.0.3 for a
reason specific to 6.0.3, and dufs-cloud/web sat on `~5.8.3`, two majors
older for no stated reason, with the gate reporting it current.
An entry that exists but does not cover the pin in front of it still counts
as USED for the rot check. The hold is real; this repo is simply not on the
held version, which is a stale pin to fix rather than an allowlist line to
delete.
322 tests, 100% branch coverage.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
`.fvmrc` is a declaration nothing in this fleet reads. `subosito/flutter-action`
takes its own `flutter-version:`, and that pin is what the runner installs, so
the two drift in silence and the failure mode is the worst kind: green
locally, red in CI, with no diff to explain it.
kuhylog is the live case. Its runner is on Flutter **3.44.9**, which predates
the `@awaitNotRequired` annotation, so `unawaited(Navigator.push(...))` is
`unnecessary_unawaited` on 3.47.2 here and `discarded_futures` there -- the two
SDKs demand opposite code and CI went red on a commit that is clean locally.
The fleet is spread across 3.44.6, 3.44.8, 3.47.0 and 3.47.1 with no one
tracking it.
So a workflow's `flutter-version:` / `node-version:` is now a dependency like
any other, judged against the same latest stable. That needs no separate
"these must agree" rule: two values both required to equal latest already
agree. A channel name and a `${{ }}` expression are skipped -- one is not a
version, the other resolves at run time and guessing is worse than silence.
Found real drift on its first run: both TypeScript workflows here pinned
`node-version: 24`, a floating major that lets two runs of the same commit
install different Node. Now 24.20.0.
321 tests, 100% branch coverage on every production module.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
**The gate could not see the shared Python libraries at all.** They are
consumed as PEP 508 direct references --
`crdt-sync @ git+https://github.com/kuhyx/utils@crdt-sync-v0.5.1#subdirectory=crdt-sync`
-- which parsed as an unpinned PyPI package that does not exist on PyPI. That
answer is undeterminable, not stale, so wake-alarm sat on gatelock-v0.4.1
against v0.7.1 and crdt-sync-v0.5.1 against v0.9.0 with a green gate. They are
git-tag dependencies now, judged the same way the Dart libraries are.
A ref that is a branch or a SHA still parses as before: there is no version
in it to compare.
The line is found textually when the key indexer cannot help. A TOML
dependency array holds bare strings with no `key =`, so these findings would
otherwise report line 0 and make the fix a search.
Both libraries also had their dependency upgrades land after their newest tag
(81d2493), so anything moving to "latest tag" would have taken the pre-upgrade
constraints. Cut 0.9.1 and 0.7.2; version bump only.
315 tests, 100% branch coverage.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Every Flutter app here declares `flutter_launcher_icons` twice: as a dev
dependency, and as a TOP-LEVEL configuration block for the same tool. The line
lookup broke ties by indentation alone, so the top-level block won and the
gate told you to fix a line that carries no version at all -- lyricanki
reported `pubspec.yaml:64` while the caret being complained about is at 48.
The pubspec parser now says which top-level keys may hold a version, and a key
found outside them is only a fallback. `environment` is in that list on
purpose: without it the `sdk:` inside a `flutter: {sdk: flutter}` block would
outrank the SDK constraint it is meant to find.
Only the pubspec parser passes the hint. JSON and TOML indent their section
headers differently, so they keep the old behaviour unchanged.
310 tests, 100% branch coverage.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Most of these configs interleave local and remote hook repos -- diet-guard,
screen-locker and wake-alarm carry nine `- repo:` blocks each. Appending at
end of file lands the hook under whichever block happens to be last, and a
local hook definition handed to a remote repo fails with an error naming an
unknown id rather than the real problem. diet-guard's last block happens to be
`local`, so this would have worked by luck there and broken elsewhere.
A config with no local block now refuses rather than guessing.
308 tests, 100% branch coverage.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
The gate is three files per repo -- a delegate, a pre-commit hook entry and a
CI workflow -- and Phase 3 needs them in sixteen more repos. Hand-replication
is precisely how the 250-line cap ended up shipping under four different hook
ids, two of which were independent reimplementations rather than delegates, so
the copy is now a script and the templates have exactly one home.
scripts/install_dependency_freshness_gate.sh <repo> [--check] [--fvm]
Idempotent, and it rewrites a copy that has drifted from the template rather
than leaving it. `--check` reports without writing. `--fvm` pins the Flutter
SDK, and only in a repo that actually holds a pubspec.yaml -- an .fvmrc in a
Python repo declares a toolchain nothing there builds with. An unresolvable
SDK version leaves the pin alone and exits 1: guessing would pin every repo to
a number nobody chose.
The pre-commit block is APPENDED rather than parsed and re-emitted. Every one
of these configs carries comments explaining why its hooks exist, and a YAML
round-trip through the standard library drops all of them.
306 tests, 100% branch coverage on every production module.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
sync_settings_ui 0.4.1 and crdt_sync_flutter 0.3.1 both pinned the v0.11.0
tag, which predates crdt_sync_dart's exact pins -- so anything taking these
libraries resolved the shared package to its pre-upgrade constraints.
`flutter pub get` re-resolves cleanly in both; 88 tests green in
crdt_sync_flutter, 35 in sync_settings_ui, 321 in crdt_sync_dart.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Two things, because the first is what blocked the second from committing.
**The rot check was scope-blind.** pre-commit passes only the staged
manifests, so a run that sees no package.json cannot learn anything about
whether the fleet-wide typescript hold is still needed -- yet it concluded the
entry was dead and exited 2. Staging two pubspec.yaml files in utils was
enough to make the repo uncommittable. The dead-entry check now runs only
under --all, which is CI and the manual whole-repo run; a subset scan has seen
a subset by construction.
**crdt_sync_dart 0.11.1 and design_system 0.2.1.** Both had dependency
upgrades land after their newest tag, so a consumer moving to "latest tag"
would pick up the pre-upgrade constraints (crdt_sync_dart-v0.11.0 still
carries `crypto: ^3.0.7`, `http: ^1.6.0`, `lints: ^5.0.0`) while carrying its
own new exact pins -- the unsatisfiable-resolution case exact pins create.
Version bump only; the dependency work is already in 922fb36 and 704c67e.
The allowlist end-to-end tests moved to their own file for the 250-line cap,
and `run`/`canned` moved to conftest so both files share one definition.
`canned` is no longer autouse: the resolver tests patch `_fetch` themselves.
293 tests, 100% branch coverage on every production module.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Two things that were fine in utils and would not have been in the next forty
repos.
**The allowlist is now fleet-wide plus per-repo.** `typescript-eslint` blocks
TS 7 in EVERY repo that pins typescript -- eight of them and counting -- and a
repo-only allowlist meant hand-copying one entry into eight files that then rot
independently. That is the four-way fork of the 250-line cap, reproduced inside
the mechanism built to avoid it. `~/utils/dependency-freshness.allowlist.yaml`
is inherited by every repo; a repo entry for the same `ecosystem:package`
overrides it.
Inherited entries are exempt from the no-longer-needed check everywhere except
the repo that owns the file. Without that carve-out a fleet-wide hold on
typescript exits 2 in every Flutter app -- it excuses nothing there, which is
the normal case, not rot -- and those repos become uncommittable. Confirmed
against punchme, which now exits 0 while utils still reports the entry as in
use.
**`quarantine.py` bypassed the cache entirely.** It ran for every npm finding
and fetched the FULL packument -- 7MB for react, 16MB for typescript -- with no
TTL and no reuse, inside a pre-commit hook. One finding in utils, but the JS
repos ahead have 16 to 37 each. Now cached under the normal 6h TTL, keyed
`<name>@<dist-tag>`: the tag has to be part of the key rather than clamped
afterwards, because clamping returns the ceiling and the ceiling is frequently
the very release the quarantine is excluding.
**Both cache and shared allowlist are now redirected by AUTOUSE fixtures.** A
quarantine test had already seeded a fake answer for package "x" into the real
~/.cache/dep-freshness/registry.json, and the next run read its own pollution
back and passed for the wrong reason. Removed the entry; the fixture makes it
unrepeatable.
292 tests, 100% branch coverage on every module.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Deliberately the last step, not the first. All eleven manifests here are now
on latest stable -- four Dart libs, two Python packages, two TypeScript
packages -- so `--all --strict` exits 0 and this can be a gate rather than a
permanent red light. Installing it any earlier would have taught everyone to
ignore it.
Unlike every other repo's copy, this one runs `scripts/check_dependency_freshness.sh`
directly instead of checking kuhyx/utils out into `.utils`: this repo IS the
gate.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Finishes the last two of the eleven manifests in this repo. Exact-pins every
devDependency and takes three majors -- @testing-library/jest-dom 6 -> 7,
jsdom 29 -> 30, pnpm 10.13.1 -> 11.24.0 -- with lint and coverage green in
both (ts_core 42/42, web_ui 102/102, 100% branches).
**TypeScript stays at 6.0.3, and this is the campaign's first real
unsatisfiable conflict.** TS 7.0.2 is latest, but typescript-eslint 8.68.0 --
itself the latest release -- declares `typescript: ">=4.8.4 <6.1.0"` and throws
"does not support TS 7.0" as eslint loads its config. There is no 9.x. Taking
TS 7 would mean dropping every type-aware lint rule from both packages, so the
compiler waits for the linter. Recorded as a `transitive:` allowlist entry,
which is a predicate rather than a date: the gate re-checks the blocker each
run and the entry clears itself when upstream ships support. First use of the
allowlist, and the loud banner now prints on every run here.
**pnpm 11 also made the gate wrong, and the gate was fixed rather than pnpm.**
pnpm 11 quarantines packages published inside a 24h window -- a supply-chain
measure against the period when a compromised publish is live -- and refused
@testing-library/react 16.3.3, published 18h earlier. Reporting a repo as
behind a version its package manager will not install is a finding nobody can
act on: the hook fails, and so does the fix it asks for. `quarantine.py` now
narrows npm's "latest" to the newest release old enough to install, bounded
above by `dist-tags.latest` so a maintenance-line release never outranks the
tag. It fetches the FULL packument (7MB for react, 16MB for typescript) and so
runs only after a finding already exists -- a clean run pays nothing, which a
test asserts by making the fetch raise.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Two npm-specific corrections found by running the gate over web_ui.
**`peerDependencies` must not be exact-pinned.** The gate was reporting
`react: ">=19"` as "not exact-pinned", and acting on that would have been
actively harmful: a peer range declares what a CONSUMER may bring, so pinning
it forces every consumer of @kuhyx/web-ui onto one exact React. Peers are now
judged the way toolchain ranges are -- does the range still admit latest? --
and only reported when it does not.
**`packageManager` is a real dependency.** corepack enforces it, so
`pnpm@10.13.1` is an exact pin that nothing was checking. It is now read and
compared, which immediately surfaced that both TS packages sit on pnpm 10.13.1
against 11.24.0.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Sixteen `>=` floors become exact pins across the two Python packages, taking
five majors with them: mypy 1.13 -> 2.3.1, pylint 3.3 -> 4.0.7, pytest 8 -> 9,
pytest-cov 5 -> 7, bandit 1.7 -> 1.9.4, plus ruff 0.15 -> 0.16.5 and
requests/types-requests. A `>=` floor is satisfied by everything newer, so it
told a checker nothing about whether these repos were actually current.
Verified in a clean venv per repo, which is what both CI workflows do
(`pip install -r requirements.txt`): gatelock 389 tests at 100% coverage under
xvfb, crdt-sync 432 tests at 100%. No test change was needed for any of the
five majors.
**Open, and deliberately not in this commit:** `.pre-commit-config.yaml` pins
these same tools AGAIN via `rev:` (ruff v0.15.2, mypy v1.13.0, pylint v3.3.2),
independently of requirements.txt, and the gate does not read `rev:` pins at
all -- so the linters CI actually runs are still on the old majors. Bumping
them is a separate and much larger job: ruff 0.16 raises 71 findings here
(CPY001 alone accounts for many, since this repo selects ALL) and mypy 2.x
raises 60, mostly stricter implicit-re-export rules. One major per commit, and
that is several.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
`types-requests==2.33.0.20260712` was reported as "not exact-pinned" against
its own value: the regex capped the release segment at three components, and
PyPI stub packages date-stamp a fourth. PEP 440 places no such limit.
Found by running the gate over crdt-sync's newly pinned requirements.txt,
which is the only manifest in the fleet with a four-part pin.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Both were the oldest floors left in the fleet -- `http: ^1.2.0` while every
sibling was on ^1.6.0. Neither moved a resolved version: pubspec.lock is
untouched, so this is a declaration change, and analyze / 24 tests / 75-line
100% coverage are all unchanged.
This is the first real repo to exercise the three-way manifest / lockfile /
registry check, since it is the one library here that tracks its pubspec.lock
while its four siblings gitignore theirs. Both directions confirmed against a
copy of this repo: a lock resolving 1.5.9 under a manifest pinning 1.6.0 is
reported as "manifest and lockfile disagree", and staleness correctly takes
precedence over it when both apply.
Version 0.3.0 -> 0.3.1, tag cut. Four consumers pin it by git tag
(home_inventory, todo, diet-guard, wake-alarm) and move when their turn comes.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Every CI workflow clones kuhyx/utils into `.utils/` *inside* the repo being
checked, so `--all` walked utils' own manifests and failed the consuming repo
for staleness in a directory that repo does not own and cannot fix.
Caught by punchme's very first CI run: locally `--all --strict` exited 0, and
the same command on the runner reported twenty findings, all of them in
`.utils/web_ui/package.json` and `.utils/ts_core/package.json`. Exactly the
kind of local/CI divergence the gate exists to prevent, in the gate itself.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
Exact-pins every registry dependency (crypto 3.0.7, google_sign_in 7.2.0,
http 1.6.0, shared_preferences 2.5.5, url_launcher 6.3.2, uuid 4.6.0) and takes
flutter_secure_storage 10.3.1 -> 11.0.0, a major.
The major is safe here for a specific reason, not by assumption. 11.0.0 removes
the algorithms deprecated in v10 and makes data written by them unreadable --
but this package has been on ^10.x throughout, and v10 migrated that data
automatically. It also removes `encryptedSharedPreferences` and
`sharedPreferencesName` from `AndroidOptions`; keystore.dart constructs a bare
`FlutterSecureStorage()` and passes no AndroidOptions at all, so neither is
reachable from here. The remaining break is minSdk 24 / compileSdk 37, which
consuming apps inherit from `flutter.minSdkVersion` (Flutter 3.35 already
raised its own floor to 24) and which fails a Gradle build loudly if wrong.
Analyze clean, 88 tests green, coverage held at 202/202 (100%).
Also installs the dependency-freshness gate in pre-commit -- the first repo to
carry it. Pre-commit only, not CI: the other ten manifests here are not
upgraded yet, and `--all` in CI would be permanently red until they are. The
`files:` regex means a source-only commit makes zero network requests.
Proven in both directions through the hook itself, not just the CLI:
crdt_sync_flutter/pubspec.yaml passes, github_device_auth/pubspec.yaml fails
and names http ^1.2.0 and url_launcher ^6.3.0, and a .dart path is skipped
by the filter.
Version 0.2.1 -> 0.3.0; consumers move their git pins after the tag.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
A caret range's *floor* is the only comparable number it carries, and all four
libs sat at ^10.2.0 while 10.3.0 was current. The Q13 carve-out lets these lint
packages keep a caret; it does not let the floor rot.
Deliberately its own commit, separate from any dependency bump: a lint-package
major/minor lands new rules across four packages at once, and tangling that
with a resolution change would make an analyze cascade indistinguishable from a
version conflict. `flutter analyze` is clean in all four, and all four suites
pass unchanged (88 / 68 / 24 / 35).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
"Are we on the newest version?" was not mechanically answerable across these
repos: constraint styles had drifted per-ecosystem and a caret range is
"newest-compatible" by definition, which gives a checker nothing to compare.
This gate makes it answerable and then enforces the answer.
Checks two things at once -- that every dependency carries an exact pin, and
that the pin equals its registry's latest STABLE release -- across pub.dev,
PyPI, npm, crates.io, the Go proxy, kuhyx/utils git tags, and the Flutter /
Node / Python toolchains.
Three deliberate design points:
* Pre-releases are rejected per-ecosystem, because every ecosystem leaks them
differently and each leak fails GREEN. npm lets a maintainer point
`dist-tags.latest` at an rc; crates.io's `max_version` includes them; PyPI's
legacy `info.version` includes yanked releases. Unit-tested with fixtures,
since an end-to-end run cannot surface a wrong "up to date".
* Offline, the gate serves an expired cache entry and PASSES with a DEGRADED
banner (exit 3 only under --strict, which is CI). `--no-verify` is banned
here, so a hook that hard-failed offline would leave no way to commit at all.
* The allowlist has two entry classes. `blocked_by: transitive:<pkg>@<ver>` is
a predicate that clears itself when upstream moves and must NOT carry a
date; everything else is discretionary and requires `expires`, capped at 90
days. Exact pins plus latest-everywhere is provably unsatisfiable when a
dependency internally constrains a shared transitive, and expiring the
predicate class on a calendar would turn the gate red for a reason no commit
could fix. An entry with nothing left to excuse is itself an error.
One hook id, one shim, one shared implementation -- always delegating, so it
cannot fork the way the 250-line cap forked into four ids, two of which were
independent reimplementations.
256 tests, 100% branch coverage on every module of the gate. Also adds the
workflow that runs them, which incidentally gives md_naming's 71 tests their
first CI run.
Not yet installed in any repo: a repo that gets the gate before its deps are
bumped is instantly and permanently red, so the gate and the upgrade land
together, per repo.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CRykabMwPgDzFHcARoqpaK
connectWithPassword() had no try/catch around firebaseFactory(), unlike
connectWithGoogle() right next to it. A thrown FirebaseAuthError (wrong
password, 400 from identitytoolkit) escaped uncaught out of the button's
async onPressed, so _busy/_status never updated and the screen sat on
"Signing in..." forever with no error shown -- reproduced live via the
browser console (confirmed "Uncaught Error" immediately after the 400,
not a hung Future).
Also reports real progress stages ("Saving account...", "Signing in to
Firebase...") instead of one static string, clears the bad password on a
confirmed rejection (previously only the null-client branch did, letting a
background sync tick keep retrying it), and surfaces the actual failure
reason in the status text instead of a generic "rejected" message.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XATAXuMzpYggWyTBPGyiSN
The failure message named refactor_claude_todo.md, which the markdown
namespace migration renamed to TODO-file-length-250.md. A gate telling
you to read a file that no longer exists is worse than one that says
nothing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A47aX5DJwmA3QFn3pkEWi7
Markdown across every repo had accumulated a dozen ad-hoc names
(refactor_claude_todo.md x23, DESIGN_AUDIT_TODO.md, NEXT_SESSION,
HANDOFF, PLAN, SPEC) with nothing distinguishing a live task from a
finished record. An audit found docs asserting work was pending that
shipped months earlier, and one asserting completion while the work
was open.
Four namespaces now: README.md, CLAUDE*.md, DOCS*.md, TODO*.md. Task
files carry the literal "REMOVE ME AFTER FINISH" and are deleted when
the work lands.
Enforced bidirectionally -- a TODO without the marker fails, AND any
file carrying the marker that is not named TODO*.md fails. Without the
reverse rule a task can be renamed into the permanent namespace and
quietly live forever, which is the failure being fixed.
md_naming/ mirrors the file_length topology and imports its tables
(EXCLUDED_DIRS, THIRD_PARTY_REPOS, VENDORED_ANYWHERE, GENERATED_PATTERN)
rather than restating them, so the two gates cannot disagree about the
same file. 71 tests, 100% branch coverage.
stale.py warns on TODOs past 90 days but never fails: no machine can
prove a task is finished, so the honest mechanism is a nudge.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A47aX5DJwmA3QFn3pkEWi7
Item 5 was recorded as "PASS (partial, reset check pending)". Now verified:
`chattr +i /etc/hosts` in a sandbox gives `----i-----------------`; after
`vm reset` the same file reads `----------------------` and accepts a write.
Worth having measured rather than assumed. Immutability is exactly what makes
the hosts guard hard to undo on a real machine -- `rm` fails EPERM -- so
"reset discards it wholesale" is the strongest form of the reset guarantee and
the one most worth being sure of.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014wfxvsYxKM5xDXoDbkKi5u
Two fixes to DISCOVERY_TEST.md, both found by re-checking claims instead
of trusting them.
The .claude remote: `git branch -vv` + `ls-remote` confirm main DOES track
origin/main on kuhyx/claude-config-local, and `gh repo view` says that repo
is PRIVATE. The correction was right but stated the wrong load-bearing
fact -- what matters when telling a future session to push there is the
visibility, not merely that a remote exists. Now says so, and says to
re-check rather than trust the line.
The contamination: NEXT_SESSION_INSTALLER_FIX.md, added to the root of
~/testsAndMisc the same day, is about hosts/install.sh -- the exact file
the discovery prompt names -- and contains "Sandbox first, always ...
~/utils/vmbox". One `ls` at that repo root leaks the answer, which is a
likelier path than the ~/utils grep already noted, and this session created
it. Records it and offers the pacman wrapper as an uncontaminated
substitute prompt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
The sandbox-first rule and the vmbox-testing skill only pay off if a
session with no memory of building them reaches for the sandbox on its
own. This is the test for that: a pasteable prompt (install the hosts
guard and confirm it enforces) that never mentions vmbox, sandboxes, VMs
or the skill, plus a Pass/Partial/Fail rubric and the follow-up.
Deliberately NOT executed by the session that wrote it -- that session
knew all about vmbox, so its behaviour would prove nothing, and a subagent
either inherits that context or gets the task framed by it.
Chose the hosts guard over the shutdown timer because a Fail should be
cheap to lose: it leaves an immutable /etc/hosts rather than a surprise
poweroff. The rubric carries the undo commands next to the Fail
definition so a failed run is not discovered weeks later.
Records that ~/.claude DOES have a remote (kuhyx/claude-config-local),
correcting an earlier note that claimed main there is remote-less; the
fix on a Fail is the skill's description: frontmatter first, then the
CLAUDE.md block, and both need committing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
Replaces the handoff prompt with the next three pieces of work.
Job 1 lands the firmware guard for the bug the sandbox found: boot-repair
deletes the only bootable kernel on a BIOS/GRUB box because its "orphaned
kernel shadowing the ESP" heuristic never checks /sys/firmware/efi. The vmbox
guest IS such a box, so the fix is verifiable in the same place the bug was.
Job 2 writes the install_core_system.sh findings into a prompt in the repo
that owns that code. The two dead module paths resolve to ~/screen-locker and
~/steam-backlog-enforcer (checked on disk, not assumed), which makes the
installer cross-repo and is itself a question for kuhy rather than a guess.
Job 3 is a test of whether a fresh Claude discovers the sandbox rule on its
own. It is written, deliberately NOT executed: running it in the session that
built the tooling, or as a subagent briefed by that session, measures nothing.
The prompt says so up front, since it constrains the whole session.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
The previous commit skipped the poweroff settle when `ssh_rc != 255`, on the
reasoning that a successful poweroff kills the ssh connection and ssh reports
255. That holds for the ssh transport and for nothing else. `_run_transport`
falls back to the serial console whenever ssh does not answer -- and the
README calls serial "the transport of record for shutdown tests" -- where the
exit code comes from serial_exec.py and is 0 even while the machine is already
on its way down.
Result, reproduced: `VMBOX_TRANSPORT=serial vm run <vm> 'sudo systemctl
poweroff'` reported "still running" for a guest that had cleanly powered off,
with SHUTDOWN{guest:true} in events.jsonl and "reboot: Power down" in the
serial log. The one thing this tool exists to get right, silently wrong. My
five verdict re-tests all went through ssh, so none of them caught it.
Grepping the serial log for shutdown markers instead does not work either:
they land a second or two after the command returns, so the check loses the
race. The fix waits a short grace period (default 3s) for any sign of a stop
before committing to the 30s wait. Warm runs go from 0s to 3s; that is the
honest price of a correct verdict.
Re-tested: clean poweroff, reboot and panic on BOTH transports, plus
tests/destructive_demo.sh 7/7.
Also, per "a fix that needs a human to remember a flag is not a fix": the X
session wait is now automatic on the branch that actually boots the guest --
the only one that can race tty1's autologin -- instead of requiring
VMBOX_X_WAIT. Warm runs never reach that branch. The env var remains an
override. README numbers corrected to the measured 14s/3s and ~100s.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
`vm run` took 41s cold / 30s warm to run `true`. Both were vmbox waiting on
itself. Now 12s / 0s, with all five shutdown verdicts re-tested unchanged.
- _run_settle waited up to 30s for the kernel's "reboot: Power down" marker
UNCONDITIONALLY, including on the majority of runs that leave the guest up,
where that marker is never going to appear. It now settles only when the
guest has actually stopped, or when ssh returned 255 (what a successful
poweroff looks like from the host).
- The ssh readiness polls used a 5s ConnectTimeout. QEMU's user-mode
networking ACCEPTS the forwarded connection while the guest still has
nothing on :22, so each probe blocked for the full timeout instead of
failing fast: a guest reachable at ~10s was reported up at ~45s. Fixed in
both the sandbox and build paths, via an env override -- ssh honours the
FIRST value for an option, so a second -o could not have worked.
Making runs fast exposed a race: sshd now answers BEFORE tty1's autologin has
started Xorg, so the X environment could be missing on the first run after a
boot. `VMBOX_X_WAIT=<seconds>` waits for the session; it defaults to 0 so an
ordinary run never pays for a graphical session it is not using.
Build: the host's /var/cache/pacman/pkg is offered to the build guest
read-only (`readonly=on` AND an `ro` mount, because it is the real host cache)
as an extra CacheDir after the guest's own writable one, so a package the host
lacks still downloads rather than failing the build. This removes the 396 MiB
the build used to fetch. Host cache verified byte-for-byte identical across
four builds: same file count, same size, same mtime.
Build time itself moved only 103.8s -> 100.3s. Per-phase timings (also added
here) show why: 47s of it is the build guest's cloud-init first boot, and that
is NOT datasource probing -- `cloud-init analyze blame` totals 2.27s. Left
unexplained rather than guessed at; SESSION_RESULTS.md records the evidence.
Also: `vm scp`, which lib/ssh.sh could always do but the CLI never exposed,
and provision.sh split at the 250-line cap.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
Testing boot_recovery produced a guest that cannot boot: boot-repair read
/boot/vmlinuz-linux and initramfs-linux.img on this BIOS/GRUB guest as
"orphaned kernel files shadowing the ESP" and deleted them, leaving the
sandbox at a GRUB prompt. That is a legitimate sandbox outcome -- destroying
the guest is what the tool is for -- but vmbox handled it by hanging.
Two independent unbounded waits, both fixed:
- vm_wait_ssh counted only its `sleep 2` calls, ignoring the up-to-5s
ConnectTimeout each failed probe spends inside ssh. A nominal 150s wait ran
past 400s (measured, then cut short by the harness). It now works to a wall
clock deadline: the same guest is now reported unreachable in 156s.
- _run_recover_rc reboots the stopped guest to read the recorded exit code,
and fell through to an unbounded serial console read: 180s for a prompt
that never comes plus 300s for a command that never runs, all AFTER the
verdict had already been printed. Recovery is best-effort by definition, so
both bounds are now short (60s/30s) and overridable.
serial_exec's timeouts become env-overridable to make that possible.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
README documented `bats tests/test_vmbox.bats` covering "name validation,
meta handling, serial rotation and the full verdict table", and the handoff
made it a done-condition, but the file did not exist. Written to that spec:
39 tests, no VM boot, well under a second.
VMBOX_HOME is redirected to a per-test mktemp dir, so the suite can create
and delete VM state without any chance of clobbering a live sandbox's overlay
or pidfile; one test asserts every path helper stays inside it.
The verdict cases encode the distinctions the design turns on rather than just
exercising the function: guest:true with a truncated serial log is DIRTY (3)
and not a clean poweroff, POWERDOWN alone proves nothing and must read as
"none", an unrecognised shutdown reason fails closed at 6 rather than passing
silently, and events.jsonl is read last-event-first so a previous boot's
poweroff is never mistaken for this run's outcome.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
The image ships Xorg + i3 on tty1 precisely so locker and i3 tests can run,
but `vm run` executes through `sh -c`, which reads no profile. Every X tool
therefore landed with no DISPLAY and no XAUTHORITY and failed with
"Could not determine i3 socket path" -- indistinguishable from "this sandbox
has no X server". testsAndMisc's i3-configuration installer failed that way;
with the environment resolved it exits 0 and i3-msg reports {"success":true}.
XAUTHORITY is the awkward half: startx generates /tmp/serverauth.XXXXXXXX
with a fresh random suffix every boot, so it cannot be hardcoded. Resolve it
from the running Xorg's own -auth argument, falling back to a newest-first
glob.
The `[ -f ]` guard on the source line is load-bearing, not defensive
dressing. In POSIX sh, `.` on a missing file is a SPECIAL BUILTIN error that
exits the shell outright, and `|| true` does NOT rescue it -- written that
way, every `vm run` against a base image predating this snippet silently
produced no output at all. Found by doing exactly that.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
Three changes from kuhy's follow-up:
- An explicit standing instruction that when vmbox breaks the next session
FIXES it -- not works around it, not reports it as a limitation, not quietly
falls back to testing on the host. Bugs found by real use are the return on
having built this.
- Guidance to attach to an existing sandbox or create one as appropriate,
rather than tearing down and rebuilding per command (`vm reset` is ~2s).
- A build-speed job with measurements rather than guesses: the last build
pulled 197 packages / 396 MiB over the internet and spent 45s waiting on
cloud-init, while the host's 114 GB pacman cache already holds every one of
the packages checked. Exposing that cache read-only is the obvious first
move; trimming base-devel and shortening the cloud-init wait follow.
The smoke gate stays regardless -- a faster build that fails open would be a
bad trade.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
Two jobs, deliberately ordered. First: run real linux_configuration work
through the sandbox (the 8 Arch-only CI tests, night-lockdown, boot_recovery,
the hosts guard) and fix vmbox wherever it breaks -- it has only ever been
driven by one session against a handful of scripts, so the ~1090-file surface
will find things.
Second, and only if the first says vmbox is trustworthy: the CLAUDE.md rule
that routes script testing here by default. A rule pointing at a flaky tool is
worse than no rule, so that ordering is the point. Four questions have to be
settled before writing it -- what triggers it, whether it replaces or precedes
the host run (see feedback-verify-real-deployment-path), the hardware escape
hatch, and keeping it short since CLAUDE.md is always-on context.
Carries forward the traps that cost real time this session: diagnose an
unreachable guest with `systemctl list-jobs`, never grep a bash -x trace for
the failure, and fix the image live over the serial console rather than
rebuilding once per hypothesis.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
Captured a real 1280x800 PNG of a sandbox's i3 session straight from qemu's
framebuffer -- no VNC or SPICE viewer installed on the host. This is the path
locker and fullscreen-gate tests use, and it is safer than testing those on
the host, where a fullscreen locker can hijack input and steal focus.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
`vm reset` killed the VM and immediately recreated the overlay, without
waiting for the process to actually exit. The next boot then read a
half-detached file and failed with "sandbox did not become reachable" -- a
symptom that appears one step AFTER the cause and says nothing about it.
Reset itself was always correct (verified by hand: after
`rm -rf --no-preserve-root /etc /usr`, a reset guest reports
NAME="Arch Linux" and has /usr/bin/bash back). This only bit when a reset
followed a still-shutting-down VM closely enough to race it, which is exactly
what the destructive demo does.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
Measured between two sandboxes: 3 packets transmitted, 3 received, 0% packet
loss, 0.23 ms average.
The previous commit called this broken. It was not: the dgram transport worked
all along, but the odd/even pairing computed the wrong peer port for even
indexes, so a VM pointed `remote.port` at a port nothing had bound. Both ends
came up, addresses were right, and zero frames crossed -- indistinguishable
from a dead transport, and nothing in any log said otherwise. The tell was
`ss -lunp`: the bound ports were 12349 and 12350 while the guest was sending
to 12348. The test then compounded it by using indexes 4 and 5, which belong
to DIFFERENT pairs (4 pairs with 3, 5 pairs with 6).
Pairing is (1,2), (3,4), (5,6)... Two sandboxes created back to back are wired
together, which is the common case.
mcast= remains genuinely unusable here and is documented as such so nobody
re-tries it: lo has no MULTICAST flag and there is no multicast route, so qemu
accepts it and drops every frame.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
The peer-address service read a `vmbox.peer=` kernel argument that the
launcher never passed -- the reader was written and the writer forgotten -- so
eth1 came up DOWN with no address on every guest. It now derives the address
from the NIC's own MAC (the host allocates 52:54:00:be:ef:<index>), which
removes the coupling entirely: nothing has to be passed in, so the launcher
and the guest cannot disagree about which index a VM has.
That fixed the addressing but NOT the connectivity. `mcast=` cannot work on
this host at all -- `lo` carries no MULTICAST flag and there is no multicast
route, so qemu accepts the option and silently drops every frame, which is the
same "flags accepted, nothing happens" trap as POWERDOWN. A listen=/connect=
socket hub over loopback TCP was tried next: the hub port listens, both
guests bring eth1 up with the right addresses, and ARP still fails.
Documented as a known limitation rather than papered over. Sandboxes work
fully on their own; two guests cannot talk to each other yet.
Also corrects the destructive demo: a running Linux SURVIVES `rm -rf /usr`
because processes hold their binaries through open file handles, so sshd keeps
answering. The honest proof of destruction is that the machine cannot boot
again, so the demo now reboots it and asserts it does not come back.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
Ran kuhy's real setup_midnight_shutdown.sh inside a sandbox -- the installer
whose own output says "There is NO disable option - this is protected by a
monitor service". It created /etc/shutdown-schedule.conf under guard-lib's
immutable protection and enabled shutdown-timer-monitor.service,
day-specific-shutdown.timer and shutdown-timer-monitor-watchdog.timer.
The host was provably untouched afterwards: base image checksum OK, /etc/hosts
still carrying its +i flag, and the host's own shutdown-schedule.conf still
stamped 11:21 that morning rather than the 21:19 when the guest wrote its copy.
Two properties of that installer are now documented, both found by running it:
it is interactive (`read -r -p 'Do you want to proceed?'`, so pipe `echo y |`
since vm run closes stdin deliberately), and it is subcommand-driven, so a
bare invocation prints usage and changes nothing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
9p exports a directory TREE and does not follow a symlink pointing out of it.
The share directory held `testsAndMisc -> /home/kuhy/testsAndMisc`, so the
guest mounted /mnt/hostrepo successfully, listed the symlink, and then got
"No such file or directory" following it -- the target path does not exist
inside the guest. Measured in a live sandbox, not assumed.
`vm share <path>` now bind-mounts the directory into the share and remounts it
read-only, so the guest sees real contents while still being unable to write
to the host copy. `vm unshare <name>` reverses it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
The destructive demo asked the guest to confirm its own destruction, one step
after deleting /usr -- which removes bash, sshd and agetty. Nothing would have
been left to answer, so the check would have FAILED on a step that actually
succeeded. It now proves breakage from the host (the overlay grew, and the
guest can no longer answer at all), which is the same evidence the shutdown
verdict relies on and for the same reason: a corpse cannot report its own
death.
Step 3 also no longer recreates the sandbox. `vm reset` in step 4 is the claim
under test; recreating first would have quietly tested something easier.
README's verdict table now carries the MEASURED qmp events per guest command
rather than the inferred ones, and states the finding that motivates the whole
design: ssh returned an identical "Connection closed by remote host" for the
poweroff, the reboot AND the panic.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
`_run_exec "$name" "$@"` sat on its own line under `set -euo pipefail`, so a
non-zero return aborted the script before the verdict was ever computed. ssh
returns 255 when its connection dies -- which is exactly what a SUCCESSFUL
guest poweroff causes. The single case this tool exists to report on was the
one case that silently printed nothing.
Caught by the acceptance demo, not by the unit tests: verdict_report was
correct in isolation the whole time and passed 8/8 there. Only running the
real CLI against a real poweroff exposed the wiring.
Verified after the fix, end to end:
==> Running in 'fixtest': sudo systemctl poweroff
Connection to 127.0.0.1 closed by remote host.
ok VERDICT: clean poweroff -- guest powered itself off and reached
'reboot: Power down'
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
shutdown_verdict_demo.sh exercises every branch of the verdict table against a
real guest -- clean poweroff, reboot-instead-of-poweroff, kernel panic, and a
command that leaves the machine running. The failure branches matter as much
as the success one: a verifier that has only ever returned "pass" is untested.
destructive_demo.sh is the acceptance test for the tool as a whole: destroy
/etc and /usr in the guest, assert the guest really is broken, reset with one
command, assert it is pristine again, then assert the HOST is untouched
(/etc/hosts attributes unchanged, base image hash unchanged, /etc and /usr
still present).
Measured on the first real run, which confirms the design's central claim:
QMP reported SHUTDOWN {"guest": true, "reason": "guest-shutdown"} and the
serial log reached "reboot: Power down", so the verdict was "clean poweroff"
with exit 0 -- while ssh saw only "Connection closed by remote host", which
would have been indistinguishable from a crash or a dropped link.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdyMBGCrGVGDWtJ9xe48f3
