vaibify 0.1.2__tar.gz → 0.1.4.dev95__tar.gz

vaibify-0.1.4.dev95/.claude/skills/add-route-module/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: add-route-module
+description: Recipe for adding a new FastAPI route module to the vaibify backend under vaibify/gui/routes/. Use when the task is to expose a new group of HTTP or WebSocket endpoints.
+---
+
+# Adding a new route module to vaibify
+
+Use this recipe when you need to add a new group of HTTP or WebSocket
+endpoints to the vaibify FastAPI backend. Every route module follows
+the same contract; follow these steps in order.
+
+## Prerequisites
+
+Read these first:
+
+- `AGENTS.md` (repo root) — global rules and traps
+- `vaibify/gui/AGENTS.md` — backend contracts
+- `vaibify/gui/routes/figureRoutes.py` — small, clean reference example
+
+## Steps
+
+### 1. Create `vaibify/gui/routes/<name>Routes.py`
+
+The filename is camelCase ending in `Routes.py` (e.g., `metricsRoutes.py`,
+`userRoutes.py`). The file must declare `__all__`, provide a module
+docstring, and export a module-level function `fnRegisterAll(app, dictCtx)`.
+
+Minimal scaffold:
+
+```python
+"""<One-sentence description of what this route group does>."""
+
+__all__ = ["fnRegisterAll"]
+
+from fastapi import HTTPException
+
+
+def _fnRegisterExample(app, dictCtx):
+    """Register GET /api/<name>/{sContainerId}/<resource>."""
+
+    @app.get("/api/<name>/{sContainerId}/<resource>")
+    async def fnHandleExample(sContainerId: str):
+        fnRequire = dictCtx["require"]
+        fnRequire(sContainerId)
+        # ... implementation ...
+        return {"bOk": True}
+
+
+def fnRegisterAll(app, dictCtx):
+    """Register all <name> routes."""
+    _fnRegisterExample(app, dictCtx)
+```
+
+Notes:
+
+- Functions are about 20 to 30 lines (a guideline: split for reuse or a
+  genuine conceptual boundary, never to meet a line count). Factor helpers
+  out (`_fn…`, `_fs…`, `_fdict…`) if a handler grows.
+- The module-level `fnRegisterAll` should only call the per-endpoint
+  `_fn…` helpers. Keep it thin so tests can import it without side
+  effects.
+- For container-path joins use `posixpath`, never `os.path`. The
+  workspace root and path-validation helpers live in
+  `vaibify.gui.pipelineServer` (`WORKSPACE_ROOT`,
+  `fsValidatePathWithinRoot`, `fsResolveFigurePath`,
+  `fbaFetchFigureWithFallback`).
+- For shell-quoting container command arguments, use
+  `fsShellQuote` from `vaibify.gui.pipelineRunner`.
+- If the route needs Docker access, call through
+  `dictCtx["docker"]`; do not import Docker utilities directly.
+
+### 2. Register the module in `vaibify/gui/routes/__init__.py`
+
+Add the module name to both the `__all__` list and the
+`from . import (...)` block. Preserve the existing order grouping
+where it makes sense; otherwise append.
+
+### 3. Register state-mutating endpoints with `@ffnAgentAction`
+
+If any endpoint on the new module mutates state and a researcher
+could reasonably invoke it from the UI (run, test, verify, commit,
+create, edit, delete, push, publish, upload, write, etc.), it must
+appear in the agent-action catalog so the in-container `vaibify-do`
+CLI can translate researcher intent into the same call.
+
+Two things go together:
+
+1. **Decorate the handler.** Import the decorator and apply it
+   directly above the FastAPI path-op decorator:
+   ```python
+   from ..actionCatalog import ffnAgentAction
+
+   @ffnAgentAction("my-new-action")
+   @app.post("/api/my-thing/{sContainerId}/do-it")
+   async def fnDoIt(sContainerId: str): ...
+   ```
+
+2. **Add a catalog entry** in
+   `vaibify/gui/actionCatalog.py::LIST_AGENT_ACTIONS`. Copy the shape
+   of existing entries: `sName`, `sCategory`, `sMethod`, `sPath`,
+   `bAgentSafe`, `sDescription`. The `sName` here must match the
+   decorator argument exactly.
+
+Pick `bAgentSafe`:
+
+- **True** — execution, read-side work, test runs, agent authoring
+  (writing files, creating/updating steps the agent is working on),
+  committing canonical state, downloading inputs.
+- **False** — destructive (delete, clean, kill, force), externally
+  visible (push to GitHub/Overleaf, publish to Zenodo), or requiring
+  researcher judgment (accept plots as standard, set Zenodo metadata,
+  reorder pipeline semantics).
+
+Every state-mutating route the GUI invokes must also have a CLI
+equivalent. Register it in exactly one place:
+
+- `LIST_AGENT_ACTIONS` — callable by agents and by `vaibify do`
+  (ships into the container);
+- `LIST_RESEARCHER_ACTIONS` — `vaibify do` on the host only, never
+  shipped into the container (credential-free researcher actions);
+- `DICT_ROUTE_TO_HOST_COMMAND` — a hand-written `vaibify` subcommand
+  (credentials, typed confirmations, interactive frames);
+- `SET_GUI_ONLY_ROUTES` — genuine browser plumbing, with a one-line
+  reason.
+
+A route that mutates but is never invoked by the GUI still goes in
+`SET_INTENTIONALLY_EXCLUDED_PATHS` with a comment.
+
+Confirm registration:
+
+```bash
+python -m pytest tests/testArchitecturalInvariants.py::testAgentActionRegistered -v
+python -m pytest tests/testArchitecturalInvariants.py::testEveryGuiInvokedMutationHasCliEquivalent -v
+```
+
+### 4. Add tests
+
+Create `tests/test<Name>Routes.py`. At minimum:
+
+- A test that imports the module and confirms `fnRegisterAll` is
+  callable.
+- One test per new endpoint, using the FastAPI `TestClient`. Look at
+  existing `tests/testPipelineRoutes*.py` and `tests/testSyncRoutes*.py`
+  for mocking patterns for the Docker context.
+
+Do not add Docker-dependent tests here — those go under the
+`testContainerBuildIntegration.py`-style exclusions.
+
+### 5. Run the contract tests
+
+```bash
+python -m pytest tests/testArchitecturalInvariants.py -v
+```
+
+Expect these to pass without modification:
+
+- `testEveryRouteModuleExportsRegisterAll`
+- `testAllRouteModulesRegisteredInInit`
+- `testAllPackageModulesDefineDunderAll` (if your file lands outside
+  `routes/`, make sure it declares `__all__`)
+
+### 6. Run the new route's tests and the full suite
+
+```bash
+python -m pytest tests/test<Name>Routes.py -v
+python -m pytest tests/ -q --ignore=tests/testContainerBuildIntegration.py
+```
+
+### 7. Exercise the endpoint end-to-end if possible
+
+If the route affects the dashboard or reports container state, start a
+real container and confirm the GUI reflects the new data correctly.
+Remember: the dashboard must always reflect the true state of the
+workflow and the container. Do not cache, short-circuit, or hide
+errors.
+
+## Common failure modes
+
+- **`testAllRouteModulesRegisteredInInit` fails.** You forgot to add
+  the module to both the `__all__` and the `from . import (...)`
+  block in `vaibify/gui/routes/__init__.py`. Both are required.
+- **Import error at app startup.** The route module imports a symbol
+  that doesn't exist, or there's a circular import. Route modules can
+  import from `..pipelineServer`, `..pipelineRunner`, and domain
+  modules, but not from other route modules — those are siblings.
+- **A 500 error on the new endpoint when the container is stopped.**
+  Handlers should check container state via `dictCtx["require"]` (called with the container id)
+  early and return a clean 4xx error when the container is not
+  running. Do not mask the error — surface it.
+- **Module not picked up at startup.** Both the `__all__` entry and
+  the `from . import (...)` block in `vaibify/gui/routes/__init__.py`
+  must include the new module name.
+
+## Do not
+
+- Do not bypass `VaibifyApi` on the frontend side if you're also
+  adding a JS caller for this endpoint — route through
+  `scriptApiClient.js`.
+- Do not embed science-specific example names (planet names, system
+  names) in route paths, sample data, or test fixtures.
+- Do not add a new polling loop on the frontend without discussion —
+  see the invariants in `vaibify/gui/static/AGENTS.md`.

vaibify-0.1.4.dev95/.claude/skills/container-image-and-packaging/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: container-image-and-packaging
+description: The vaibify container image: the Dockerfile and entrypoint, the Claude/Codex/Gemini agent overlays and their shared login store, agent-facing docs inside the container, and how runtime resources are located so they ship in the wheel. Use when editing vaibify/containerImage/, vaibify/resources.py, the packaged templates, or the docs staged into the image.
+---
+
+# The container image and packaged resources
+
+Two rules dominate this area. Anything the image needs must live under
+`vaibify/` and be located through `vaibify/resources.py`, because a
+`parents[N]` walk resolves to site-packages in an install. And every
+agent in the image reads one canonical instruction file through
+symlinks -- a second real file at one of those names silently splits
+them.
+
+The repository-wide rules in `AGENTS.md` still apply; this file is
+the detail for this subsystem.
+
+## The toolchain epoch is pinned on three axes
+
+The Dockerfile pins the base image by DIGEST, the toolchain packages
+by VERSION, and the archive they come from by DATE
+(`ARG APT_SNAPSHOT_DATE`, served by `snapshot.ubuntu.com`). The third
+axis was added because the first two were not enough: Ubuntu drops
+superseded versions from its pool within weeks, so the pins stopped
+RESOLVING on a monthly cadence and every unrelated pull request went
+red waiting for a maintainer to approve something nobody can evaluate
+-- a glibc SRU changes real bytes, and no review separates "this moves
+a number" from "this does not".
+
+There is one pin list per architecture the image builds on, amd64 and
+arm64, and the shell selects the list matching
+`dpkg --print-architecture`. The base digest is a multi-architecture
+index, so a daemon pulls the manifest for its own platform and the
+toolchain packages carry that platform in their names
+(`gcc-13-x86-64-linux-gnu`, `gcc-13-aarch64-linux-gnu`); a single
+amd64 list stopped every native build on an Apple Silicon daemon at
+that step (met 2026-09-18). The two lists carry the SAME versions,
+because one Ubuntu source upload builds every architecture, and
+differ only in those suffixed names and in `libquadmath0`, which has
+no aarch64 build. Any other architecture is refused before apt runs,
+with its own message, so that refusal can never read as a withdrawn
+version. `tools/checkToolchainEpoch.py --verify` reads every list
+against its own `binary-<arch>` index and fails first if the lists
+disagree on a version; `--architecture` narrows either tool, and
+`checkToolchainPinDrift --write` bumps every list that pins the
+package. Regenerate a list with `apt-get install -s` under
+`--platform linux/<arch>`, per the Dockerfile's comment.
+`fresh-image-build` runs one leg per list (an amd64 and an arm64
+runner), because a daemon only ever installs the list for its own
+platform, so a single-architecture lane verifies half the file. Two more
+traps in the same block, both met the same week: the base image is
+pinned by digest, so when that digest already ships a NEWER libc than
+the pins name, apt refuses the install as a downgrade
+("Packages were downgraded and -y was used without --allow-downgrades")
+and the answer is an epoch bump, never `--allow-downgrades`; and
+BuildKit ends a failed build by echoing the whole sixty-line step, so
+the one apt line naming the cause scrolls out of any short tail -- the
+catalog drops that echo before it looks for the reason.
+
+Four things not to undo:
+
+- **The date and the pins are one statement.** Editing either alone
+  produces an image that cannot build.
+  `python tools/checkToolchainEpoch.py --verify` is the agreement
+  check, and `fresh-image-build` runs it before the hour-long build so
+  the answer costs thirty seconds.
+- **The toolchain DATE covers ONLY the pinned block.** Every other apt
+  step reads the build's own snapshot, `APT_BUILD_SNAPSHOT` (the most
+  recent midnight UTC, passed by `imageBuilder.fsArchiveSnapshotForBuild`
+  and computed by the step itself when a plain `docker build` passes
+  nothing), so the waived packages float from one build to the next but
+  never WITHIN one. Freezing them to the toolchain date would strand a
+  researcher whose `systemPackages` name anything published since.
+  Letting them read the live mirrors again reopens the defect the build
+  snapshot closed: `security.ubuntu.com` is several servers that disagree
+  while an update propagates, each RUN step fetched its own index, and
+  one build installed a library new and found its `-dev` package old
+  (every amd64 build, 2026-09-24). No fallback to the live archive
+  either -- an unreachable snapshot stops the build and says why.
+- **The live-archive comparison never runs on a pull request.** That is
+  `toolchainEpoch.yml`, monthly, and it opens an ISSUE rather than a
+  pull request because choosing between candidate versions needs dpkg
+  ordering plus a judgment about what results rest on.
+  `testTheLiveArchiveComparisonIsNotOnThePullRequestPath` is the guard.
+- **`fsExtractToolchainBlock` anchors on the architecture test that
+  opens each list** (`[ "${sArchitecture}" = "<arch>" ] && ! apt-get
+  install`), not on the `RUN` line, because the preamble grew a
+  sources swap. It refused rather than scanning nothing when that
+  happened, which is the property to keep -- a permissive anchor
+  would have silently graded the empty set, and one that did not name
+  the architecture would hand every caller the first list. It is the
+  ONE parser of the block: the epoch tool imports it rather than
+  keeping a whole-file regex, which would merge both lists.
+
+## An image carries what it was built FROM, on two axes
+
+The recipe fingerprint (`dockerfileComposer.S_RECIPE_IMAGE_LABEL`)
+covers the texts vaibify ships. A second label,
+`configurationFingerprint.S_CONFIGURATION_IMAGE_LABEL`, covers the
+researcher's own `vaibify.yml` -- but only the fields the BUILD
+consumes. Together they answer "was this image built from these texts
+and this configuration", and the dashboard reads the second one on
+every container entry so an edit that needs a rebuild says so instead
+of being met by the old behaviour a restart later.
+
+Two things not to undo. `T_BAKED_CONFIGURATION_FIELDS` is a claim about
+what requires a rebuild: adding a field says changing it does, leaving
+one out says it does not, and both are claims about the build rather
+than preferences -- check the Dockerfile's build args, the generated
+`container.conf`, and the overlay selection before touching it. And the
+label is stamped on the BASE build alone: Docker inherits a parent
+image's labels, so every overlay carries it, where the recipe label is
+re-stamped per overlay because its value differs per chain.
+
+**`introspectionScript.py` is an f-string executed inside containers.**
+Editing it as ordinary Python loses escape sequences and string
+delimiters silently. The format-handling duplication with
+`dataLoaders.py` is also deliberate — container scripts cannot import
+from the host environment.
+
+**The entrypoint's root phase runs with a fixed system `PATH`.**
+`entrypoint.sh` calls `fnUseFixedSystemPath` before it runs anything as
+root, so a binary planted in the researcher-writable `~/.local/bin` (or
+in a directory named by `/etc/vaibify/binaries.env`) can never be the
+command a root-phase `chown` or sub-script resolves to. The
+`binaries.env` directories are prepended only in the user phase and the
+`profile.d` file. In-container agents are taught the
+`{step:<sStepId>.<stem>}` token form, never the deprecated `{StepNN.x}`.
+
+## A container may host Claude, Codex, or Gemini
+
+Container agents are overlays selected by feature flags
+(`vaibify/containerImage/Dockerfile.claude`, `.codex`, `.gemini`). Each installs **as
+the unprivileged container user**, not root, so the provider's own
+updater can replace its binary without sudo — do not "fix" that by
+installing as root, and do not add sudo to the image.
+
+**Cline is the exception to the flat-name rule.** Six of the seven
+agents read a repo-root markdown file, so a symlink serves them. Cline
+reads a `.clinerules/` **directory**, so `fnLinkClineRules` creates it
+with a symlink inside pointing back at the canonical file — a flat
+`.clinerules` symlink would be a file where a directory is expected.
+It is gated on Cline being installed, because a stray directory in the
+researcher's repository is the sort of thing that gets committed by
+accident. `tests/testEntrypointAgentDocLinks.py` fails if an agent is
+added to the skills loop without a path to the guidance, which is
+exactly how Cline came to ship with skills and no instructions.
+
+**Agent-facing docs have one source and several names.** Inside the
+container the canonical file is
+`/workspace/<repo>/.vaibify/AGENTS.md`; `entrypoint.sh`'s
+`fnLinkRepoClaudeMd` symlinks `/workspace/<repo>/CLAUDE.md`,
+`/workspace/<repo>/AGENTS.md` and `/workspace/<repo>/GEMINI.md` to it,
+and migrates a legacy CLAUDE.md in that directory into place. So write
+in-container agent guidance once, to the canonical file. Never author
+a provider-specific one — a second *real* file at one of those names
+shadows the symlink for that provider only, and the three agents
+silently start reading different instructions.
+
+(These are container paths, deliberately absolute:
+`tools/checkAgentDocsPaths.py` resolves repo-relative references and
+would flag them as broken, because they exist only inside a running
+container.)
+
+**All three agents share one login store and one user.** Each agent's
+config directory is persisted into the workspace volume and symlinked
+back into the home directory (`fnPersistAgentConfig`), so logins
+survive container recreation. This pattern predates multi-agent
+support; what changed is the blast radius. Every agent runs as the
+same container user, so file permissions isolate nothing between
+them: whichever agent is compromised can read all three providers'
+credentials, and they are reachable through the dashboard's file
+routes like any other workspace path. Treat "an agent was
+compromised" as "every configured provider's session was exposed"
+when reasoning about a threat, and do not add a fourth provider
+without revisiting that.
+
+Two more things not to undo:
+
+- The generated instructions' "Whose instructions win" section and
+  conditional conventions are a contract; do not restore unconditional
+  conventions. `tests/testEntrypointInstructionPrecedence.py` guards
+  both.
+- No credential or token on a command line or in an environment
+  variable inside an image. The JupyterLab token reaches the server
+  through a mode-600 config file;
+  `test_jupyter_token_never_reaches_a_command_line` guards it.
+
+## Runtime resources live inside the package
+
+`vaibify/templates/` and `vaibify/containerImage/` ship in the wheel.
+They used to be reached with `parents[N]` from the repository root,
+which resolves to `site-packages` in an install — so no wheel ever
+contained them and `vaibify init` printed "No templates found" and
+exited 0. Four rules follow; the full account is in
+[docs/architecture.md](docs/architecture.md) — "Packaging: why runtime
+resources live inside the package".
+
+**Locate them only through `vaibify/resources.py`.** It is the single
+place that names the trees, and `importlib.resources` resolves them
+identically from a checkout, an editable install, and a wheel. **Never
+reintroduce a `parents[N]` walk to reach package data** — and after
+fixing any resolution bug, grep for every other way the codebase reaches
+outside the package, not just the spelling that bit you.
+
+**Treat them as read-only, and give every build its own copy.**
+`commandBuild.fsStageBuildContext` mkdtemps a private context under
+`~/.vaibify/build/`, discarded on success and kept on failure with its
+path printed. It is per *build*, not per project — two dashboard clicks
+race, and refreshing a shared directory starts with `rmtree`.
+`tests/testPackagedResources.py` fails if this regresses.
+
+**Anything the image needs must live under `vaibify/`.** The curated
+agent docs at `vaibify/docs/` are **symlinks onto the Sphinx sources** —
+never replace one with a real file, which is the shadowing trap;
+`testCuratedDocsRemainSymlinksOntoTheSphinxSources` fails if you do.
+When adding one: add the symlink, extend `T_STAGED_DOCS`, extend the
+doc-map skill's table, and add the *Sphinx source* path to
+`freshImageBuild.yml`'s triggers.
+
+**Prove the distribution, not the import.** `pip-install.yml` runs
+`tools/checkInstalledDistribution.py` against an installed sdist and
+wheel. It is **release-only**, so a packaging regression can sit on
+`main` until a version is cut — after touching `vaibify/resources.py`,
+the packaged trees, or the Dockerfile `COPY` set, run it by hand
+(`workflow_dispatch`). Never make it a required status check: it cannot
+report on a pull request, so every PR would wait on it forever.

vaibify-0.1.4.dev95/.claude/skills/dashboard-state-honesty/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: dashboard-state-honesty
+description: Rules that keep the dashboard from overstating what vaibify knows: a row renders a gate's verdict rather than re-deriving it, a level cell and its rows must fail on the same set, an uncheckable remote is never red, and a configured secret this host cannot resolve degrades loudly. Use when changing WHAT a requirement row, level cell, badge, or poll payload asserts about container or workflow state. Not for explaining why a badge shows the state it shows, and not for reshaping an endpoint's JSON when every assertion in it stays the same.
+---
+
+# The dashboard tells the truth or says it does not know
+
+The GUI is the researcher's ground truth. Each contract here exists
+because a screen once contradicted the machinery behind it while every
+component was internally consistent -- which is the failure mode that
+no unit test catches.
+
+The repository-wide rules in `AGENTS.md` still apply; this file is
+the detail for this subsystem.
+
+**A failure names its remedy, or offers the diagnosis that will.** A
+2026-09-18 audit of the environment hub and the Project Hub found four
+shapes of failure reporting: the server's raw text shown verbatim
+(Docker's stderr included -- "pull access denied ... repository does
+not exist" for an image that had never been built), a description with
+no remedy ("Build failed", "Cannot load containers"), silence (a list
+frozen at its last good render after a poll 500, a Restart abandoned
+after a failed stop with no word), and a real sentence discarded on
+the server behind "Pipeline action failed. Check server logs for
+details." The rule that closes all four: every user-visible failure
+either states what to do, or ends in "Click to run a diagnosis"
+(`VaibifyDiagnosis`, backed by `GET /api/system/doctor`, which runs the
+same host checks `vaibify doctor` prints so the browser can never say
+something the terminal would not). On the server, Docker's text is
+translated at the boundary by `dockerErrorDiagnosis` with the daemon's
+words kept as evidence, a control-plane refusal passes through the
+client sanitizer in its own words because it is written for the
+researcher and names the reconcile, and a sentence that names the file
+to fix is never collapsed into a generic status. A refusal without a
+remedy is a dead end the researcher pays for in a support round trip.
+
+**A configured secret this host cannot resolve DEGRADES, and the
+telling is the load-bearing half.** `flistMountSecrets` skips it and
+the container starts (ruled 2026-09-05, making the Features page's
+"the container will still work but git push will fail" true). All three
+methods used to RAISE, before `docker run` was ever composed, so no
+container existed to inspect — a researcher met that hours after a
+wizard toggle with a `RuntimeError` naming neither the secret nor the
+remedy. A silent degrade would be strictly worse than that refusal, so
+three surfaces report it from one authority
+(`vaibify/config/secretAvailability.py`): the CLI preflight, the hub
+log at start, and the dashboard's readiness banner. The dashboard's copy is
+RECOMPUTED per settled readiness answer, never remembered — a
+researcher who runs `gh auth login` afterwards has fixed the thing it
+complains about — and only on the SETTLED answer, because the frontend
+polls readiness sixty times while a container boots and `gh auth token`
+is a subprocess. Never materialize a secret to discover that it exists;
+`fbSecretExists` is written not to.
+
+**A requirement row renders the gate's VERDICT, never re-derives it.**
+The Reproducibility-rules row computed "declared" in JavaScript as
+"the `dictDeterminism` block is non-empty", while
+`fbWorkflowDeclaresDeterminism` required a `true` waiver or a pinned
+thread count. The declare form writes `{bAcceptBlasVariance: false}`
+when submitted with nothing ticked — non-empty, and a declaration of
+nothing — so the row went green, the L3 verify refused, and every
+component was internally consistent while the screen contradicted the
+machinery (researcher-reported, 2026-08-30). The poll now ships
+`bDeterminismDeclared` and `listDeterminismIssues`; the row renders
+them. **A mirrored predicate in JS is a second authority on a question
+that has one** — the slug mirror in `scriptUtilities.js` is tolerated
+only because it is display-only with the backend enforcing. Two
+corollaries, both from the same report: a reason must distinguish the
+shapes it describes ("no block" and "a block that pins nothing" read
+identically, and one was false), and a refusal names its cause rather
+than pointing at a tab. Guarded by
+`tests/testDeterminismRowMatchesItsGate.py` and
+`tests/browser/testDeterminismRowFollowsTheGate.py`.
+
+Since 2026-10-17 the question is ONE row, and the rule holds in two
+more places. The form renders the backend's `listChoices`, `sWhy` and
+`sConsequence` verbatim and sends only the answer: the server, never
+the page, decides which execution profile an answer records, and the
+row shows the profile the poll says was recorded, not one JavaScript
+would pick. And a Level 3 verdict is shown as the SERVER's sentence
+WITH its tally ("Reproduced: published comparisons passed; N of M
+files differ in their bytes"), never recomputed from per-file outcomes
+in the page, and a pass with byte differences is worded and coloured as
+a pass. An attestation made by the byte-only verifier, or under another
+policy or profile, renders as a previous check — true about what it
+checked, not accepted now — and its staleness reason
+(`sProfileMismatch`) comes from the poll.
+`tests/browser/testAssessedVerdictsOnScreen.py` guards the verdict
+half. A step whose outputs were made under other settings or hardware
+carries the server's neutral note (`dictOutputContextNotes`), never
+red (`tests/browser/testOutputContextNoteIsNeutral.py`).
+
+**A level CELL and the rows beneath it must fail on the same set.**
+The Project header's L2 cell counts criteria from a fixed tuple
+(`_T_WORKFLOW_LEVEL2_BASE_CRITERIA`) and INTERSECTS the live blocker
+list against it — so a criterion the gates emit but the tuple omits is
+silently dropped and the cell over-reports. That shipped: the tuple
+listed only `*-verify-stale` and not `not-in-*`, so a fresh verify that
+proved published files DIFFERED painted a check above two orange
+Published-copies rows (researcher-reported, 2026-08-30). The scalar
+gate `_fbComputeLevel2` was correct throughout, which is what makes
+this class nasty — the display disagreed with itself and only the
+display was wrong. **When you add or rename an L2/L3 blocker criterion,
+check whether the workflow-scope tuple should carry it**; a criterion
+absent from the tuple is invisible to the header, not merely
+uncounted. `tests/testProjectHeaderNeverOutranksItsRows.py` is the
+kill-confirmed guard, and it also pins the opposite error: the two
+halves of one remote's check are mutually exclusive by construction, so
+neither may charge a service twice.
+
+**A container older than its own `vaibify.yml` says so, and an image
+that predates the stamp says nothing.** Everything a researcher writes
+in `vaibify.yml` that the BUILD consumes -- repositories, system and
+Python packages, base image, Python version, container user, workspace
+root, binaries, features -- is baked in at build time, and the
+dashboard used to be silent about that. One researcher corrected a
+misspelled package and a wrong branch, restarted the container, and met
+the same three warnings, having already fixed their cause on disk
+(2026-09-21). The build now stamps a hash of those fields as
+`configurationFingerprint.S_CONFIGURATION_IMAGE_LABEL`, the readiness
+answer compares it with the file as it is NOW, and the banner renders
+`listConfigurationDrift` -- the server's sentences, never a predicate
+of its own. Three properties hold it honest, and each is a way to turn
+it back into a lie:
+
+- **Run-time fields are deliberately OUT of the fingerprint.** Ports,
+  bind mounts, secrets, network isolation and the CPU/memory ceilings
+  are applied by `docker run`, so they take effect on the next start.
+  A fingerprint that covered them would send a researcher through an
+  hour-long rebuild to publish a port, which is how a true warning
+  becomes one people turn off.
+- **No label is *nothing determined*, never drift.** An image built
+  before the stamp existed carries none, and the comparison is
+  three-state for the same reason `environmentDrift` is.
+- **The stamp is the file AS WRITTEN.** The build adds the project's
+  own repository to what the container clones; that addition belongs
+  to the build context, and `fnPrepareBuildContext` works on a copy so
+  it never reaches the fingerprint. When it did, every freshly built
+  container claimed to predate the file it was built from
+  (researcher-reported, 2026-09-28) --
+  `testAFreshBuildStampsTheFileItWasBuiltFrom` drives real `git`.
+- **It rides its own key, not `saWarnings`.** That list is headed
+  "from the most recent container start"; this is a statement about a
+  file the researcher edited since, and filing it there would make the
+  banner's own heading false.
+
+`tests/testConfigurationFingerprint.py` is the kill-confirmed guard.
+
+**A remote badge pulses while vaibify is asking, and a failed ask is
+never red.** Opening a project re-checks every CONFIGURED remote
+(`POST /api/workflow/{id}/remotes/refresh`), the poll REPORTS where
+each check has got to (`dictRemoteChecks`), and the badge pulses until
+its own answer arrives. Four things hold that honest, and each is a way
+to turn it back into a lie:
+
+- A check that could not complete settles UNCHECKABLE with a reason.
+  Red means *diverged* — a claim about the remote nobody earned — and
+  the cached record on disk stays untouched
+  (`scheduledReverify.fdictAttemptOneVerify` writes only on success; do
+  not add a write beside it).
+- Which remotes pulse comes from
+  `scheduledReverify.flistSelectConfiguredServices`, the predicate the
+  scheduled loop skips on. A remote absent from `dictRemoteChecks`
+  renders exactly as it did before any of this existed.
+- A check in flight moves no colour. It has compared nothing.
+- The CHECKING timeout is evaluated when the state is READ, never on a
+  timer: the failure it covers is a worker that never returns, and such
+  a worker cannot clear its own flag.
+
+The refresh cannot move into the poll —
+`_fdictBuildWorkflowEnvelopeDetail` is built with no extra container
+execs and no network I/O. `docs/architecture.md` carries the model and
+the one accepted residual (a Run Step in the first seconds after open
+is refused by name while the checks hold the drain).
+`tests/testRemoteBadgeRefresh.py` and
+`tests/browser/testARunningRemoteCheckPulsesTheBadge.py` are the
+kill-confirmed guards; the browser one reads `animationName` off a live
+element, because asserting the CSS class alone passes against a
+stylesheet with no rule in it.
+
+- A message about what happened is built from the result payload,
+  never fixed text. The test-generation toast claimed "Standards came
+  from the LLM fallback" from 2026-04 to 2026-10 although no LLM ran.
+  Generated tests carry their generator (`deterministic`,
+  `llm-fallback`, `llm`) and the step's test rows show it.