Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

95.1 KB
Raw Blame

Show Runtime Availability

Status: proposed Owner: unassigned Repos touched: avibe, avibe-bot/vibe-show-runtime New artifact: avibe-show-runtime PyPI distribution (see W3)

1. Background

Show Page is a core Avibe capability, but the managed Show Runtime that serves it is delivered through a channel that is not as reachable as the one that delivers Avibe itself. A single transient DNS failure during an upgrade left Show Page permanently broken on a developer machine until it was repaired by hand.

1.1 Observed incident

Timeline on one macOS machine, upgrading to avibe-os 3.0.13rc3:

  1. The upgrade replaced the wheel. The new wheel pins a rebuilt darwin-arm64 archive (a9c3ef28…) even though runtime_version is unchanged (64e2e610e4107304bdc8ce2f2d387d76be6f0a0b).

  2. The service restarted. The previous Show Runtime sidecar self-terminated (parent process exited; shutting down orphaned server).

  3. The startup dependency reconcile treated the already-working local install as "not installed" (see §2.1) and began a mandatory ~21 MiB download.

  4. github.com DNS resolution failed three times:

    Dependency request attempt 1/3 failed for
    https://github.com/avibe-bot/avibe/releases/download/gh-v3.0.13rc3/vibe-show-runtime-node-darwin-arm64.tgz (dns)
    ...
    core.dependency_network.DependencyNetworkError: DNS lookup failed for github.com
    Startup dependency reconcile completed with issues: show_runtime=runtime_archive_download_failed
    
  5. _install_attempted latched for the process lifetime. Every later ensure() short-circuited: no retry on request, no background retry. ui_stderr.log mtime stayed frozen while later /show/ requests were served.

  6. Every /show/ request fell through a bare except Exception to the recovery HTML, whose spinner has a 30 s CSS delay — presenting as an endless spinner.

  7. Network was healthy minutes later. The runtime never installed until the operator clicked install in Settings.

1.2 Delivery-channel asymmetry

install.sh already treats weak-network users as a first-class case for the Python package (install.sh, install_avibe):

# Try in order: PyPI -> China mirror (tsinghua) -> GitHub
if   install_package_candidate "$PACKAGE_NAME"; then                  # PyPI
elif install_package_candidate "$PACKAGE_NAME" --index-url https://pypi.tuna.tsinghua.edu.cn/simple
elif install_package_candidate "git+https://github.com/${REPO}.git"

The Show Runtime archive has no equivalent. It is fetched from a single hard-coded github.com release URL with no mirror and no fallback. A user who can install Avibe cannot necessarily obtain its Show Runtime. This is a designed asymmetry, not an accident of the incident above.

2. Root causes

Five independent layers had to hold for the outage to occur. Each is separately fixable.

2.1 Install identity is over-broad

core/show_runtime.py, _manifest_install_dir:

fingerprint = hashlib.sha256(f"{manifest.digest}:{archive.sha256}".encode("utf-8")).hexdigest()[:16]

_manifest_install_matches requires all five fields to match, including manifest_sha256 == manifest.digest.

manifest.digest is the digest of the whole manifest file, which describes all six platforms. Any manifest edit — including one that only rebuilds win32-x64 — changes that digest and therefore invalidates the install on every other platform. macOS and Linux users would re-download ~21 MiB for a Windows-only change, with nothing about their own runtime changed.

2.2 The runtime bundle is not reproducible, and runtime_version is an incomplete identity

vibe-show-runtime/scripts/bundle-vibe-remote.mjs writes a fresh package.json into a temp stage directory using floating ranges, then runs npm install (not npm ci) in a directory that has no lockfile:

dependencies: {
  "@avibe/show-runtime": "file:./packages/runtime",
  "@avibe/show-ui": "file:./packages/ui",
  "@avibe/show-sdk": "file:./packages/sdk",
  "@vitejs/plugin-react": "^5.1.1",
  react: "^19.2.0",
  "react-dom": "^19.2.0",
  vite: "^7.2.4"
}

The repo's committed package-lock.json governs the repo's own build dependencies; it does not govern the bundled node_modules. Consequences:

  • Two bundles built from the same source commit can contain different Vite/React/plugin versions. The 1800-byte delta between the two archives observed on disk is very likely a real content difference.
  • runtime_version (the vibe-show-runtime commit SHA) therefore does not fully identify a bundle. archive.sha256 is the only complete identity.
  • Byte churn with no source change is expected rather than exceptional, so the identity check in §2.1 fires routinely.

The archive is then created with a shell tar -czf, which records mtimes and directory traversal order — a second, independent source of nondeterminism.

Note: the archive contains no Node binary. It bundles package.json, package-lock.json, packages, and node_modules; per-platform builds exist because node_modules carries platform-native binaries (esbuild, rollup, lightningcss). The runtime uses the system Node, constrained by the manifest's minimum_node (^20.19.0 || >=22.12.0).

2.3 One failure latches for the process lifetime

core/show_runtime.py:

self._install_attempted = False
...
if self.auto_install and not self._install_attempted:
    self._install_attempted = True
    command = await asyncio.to_thread(self._install_managed_runtime)

A single failure — transient or not — disables every subsequent install attempt until the process restarts. The module already holds the correct convention a few lines above, used only by capability negotiation: _capability_retry_deadline, _capability_retry_attempt, and _show_runtime_capability_retry_delay.

2.4 The archive has exactly one network source

_resolve_manifest_archive (the default manifest-cache path) has two sources: the local downloads/<sha256>.tgz cache, and a network GET of archive.url. On a machine that has never held the archive, that single GET is the whole delivery mechanism, and it points at one hard-coded github.com host.

_copy_packaged_runtime_archive — which reads a wheel-bundled archive from vibe/show_runtime/ — is only reachable from the legacy archive source path (_resolve_prebuilt_archive). The default path never consults it.

The wheel ships only vibe/show_runtime_manifest.json (~2 KiB) plus an empty vibe/show_runtime/.gitkeep. The release pipeline actively asserts the archives are absent (.github/workflows/publish.yml, and the same check in release_ai.yml):

if archives:
    raise SystemExit("Wheel unexpectedly contains Show Runtime archives:\n" + ...)

AGENTS.md §9 currently states that GitHub pre-release wheels carry bundled vibe/show_runtime/*.tgz. That contradicts the enforced pipeline and is stale.

2.5 The failure is invisible and the recovery page misleads

Both /show/ call sites wrap _show_page_runtime_response in a bare except Exception and log at logger.debug, discarding the reason code. The incident appears nowhere in vibe_remote.log.

show_page_runtime_recovery_html takes no reason parameter. It renders "Ready to visualize" plus a copyable prompt telling the agent to replace src/App.tsx and check the Vite console — actively wrong for an infrastructure failure. SHOW_RUNTIME_RECOVERY_LOADING_DELAY_SECONDS = 30 delays the state change by 30 s and is simultaneously passed to the node CLI as --fallback-delay-seconds, conflating two unrelated concerns.

3. Current update strategy (for reference)

  • The runtime version is locked to the Avibe version. The manifest is baked into the wheel; there is no independent runtime update, no version discovery, and no floating "latest" on the default manifest-cache source. Non-default sources are inconsistent here: _RUNTIME_GITHUB_REF = "main" and releases/latest/download do float.
  • Update trigger is identity mismatch (§2.1), evaluated by the one-shot startup dependency reconcile after a restart.
  • core/update_checker.py _perform_update calls do_upgrade and restarts. It never touches Show Runtime. The runtime re-download is therefore a silent side effect of an Avibe auto-update, executed at the moment the previous sidecar has just been killed.
  • Retention is _MANAGED_RUNTIME_ROLLBACK_INSTALLS = 1: the current install plus one previous install are kept, and the downloads/ archives those two need are protected from GC.
  • The switch is not atomic. The new identity becomes authoritative before its bytes are known to be obtainable. Nothing consumes the retained install.

4. Goals

  1. A completed Avibe install implies a working Show Page, over the same channel that delivered Avibe.
  2. A transient failure self-heals without a service restart.
  3. A runtime rebuild with no source change does not force any user to re-download.
  4. A manifest change confined to one platform does not invalidate other platforms' installs.
  5. When the runtime genuinely cannot be obtained, the user is told the truth and given a command that can work.
  6. No single host, registry, or vendor can make the runtime unobtainable, and every tier that carries it is one a third party already mirrors for us.

5. Non-goals and rejected options

Rejected: rolling back to a different runtime_version. The runtime's internal packages are all "version": "0.0.0"; the only version identity is the commit SHA. Compatibility ranges cannot be expressed. Avibe's scaffold imports @avibe/show-ui and @avibe/show-sdk, which ship inside the runtime bundle, so an older runtime can be missing exports the current scaffold requires. Serving a mismatched runtime is not a degraded success; it is an unverifiable failure. Never reuse an install whose runtime_version differs from the pinned one.

Rejected: reusing a same-runtime_version install with different archive bytes. Considered and dropped once §2.2 was understood. Because the bundle's third-party dependencies are resolved at build time and are not captured by runtime_version, two archives with the same runtime_version are not known to be equivalent. The correct fix is to make the archive deterministic upstream (W1), not to add an equivalence heuristic downstream.

Rejected: one universal wheel carrying all six platforms. 9.06 MiB (current wheel) + 140.8 MiB (six platforms, all managed runtimes) ≈ 150 MiB, over PyPI's 100 MiB per-file limit.

Rejected: six platform-specific wheels of avibe-os carrying the archives. This was the first version of W3. It fails on cost/benefit. The runtime changes about twice a month; avibe-os releases about six times a month. The archives would therefore be re-uploaded, unchanged, on most releases:

Bytes
Uploaded over the measured 74 days 15 releases × 6 platforms × ~21.3 MiB = 1.87 GiB
Distinct archive content in that window ~3 runtime versions × 6 × ~21.3 MiB = 383 MiB
Re-uploaded identical bytes 1.5 GiB (80%)

It also carries permanent complexity that a source ladder does not need: platform tags in hatch_build.py, a 6× wheel fan-out in two workflows, a measured glibc floor, an inverted pipeline assertion, and six extra release artifacts forever. And it addresses only §2.4, by routing around the single source rather than removing it — a machine that installs the pure fallback wheel is left with exactly today's single-source path.

Rejected as the first tier: a self-hosted CDN (Cloudflare R2 or similar). Cheap to operate, and it is the only option that needs no version scheme at all — objects can be keyed directly by commit SHA, which is a real advantage over any registry. But the entire motivation for this plan is users who cannot reach github.com, and a self-hosted origin is the one option whose China reachability we would have to solve, and pay for, ourselves. PyPI and npm are already mirrored in full, by third parties, at no cost to us. A self-hosted tier stays available as an additional tier if origin control is later wanted; it must not be the first one.

Out of scope for this plan: bundling memory_runtime (its manifest has placeholder size: 1 entries and looks unfinished) and model_hub_runtime (different manifest shape).

6. Size budget

Measured from the manifests on master:

Runtime darwin-arm64 linux-x64 win32-x64
show 22302344 23242796 24113099
git 1684366 1765892 n/a
tmux 623837 958795 n/a
per-platform total ~23.5 MiB ~24.8 MiB ~23.0 MiB

Six-platform total: 140.8 MiB. Show Runtime is the overwhelming majority; git and tmux together are ~2.5 MiB and are nearly free to include.

Current PyPI state: avibe-os 3.0.12 is a 9.06 MiB py3-none-any wheel plus an 8.79 MiB sdist; 15 releases occupy 0.18 GiB of the default 10 GiB project quota.

Measured cadence over the same 74 days: avibe-os shipped 15 releases (6.1 per month), while vibe-show-runtime main took 5 commits (2 per month) clustered into roughly 3 distinct runtime versions. The two cadences differ by ~3×, which is what makes a separate distribution the right shape (§5).

Projected under W3:

Distribution Per upload Cadence Per year Default 10 GiB lasts
avibe-os — unchanged: pure wheel + sdist 17.85 MiB ~6.1/month 1.28 GiB ~7.6 years
avibe-show-runtime — 6 platform wheels + 1 pure fallback ~130 MiB ~2/month ~3.1 GiB ~3.2 years

Each distribution carries its own 10 GiB project quota, and the largest single file is ~22 MiB against a 100 MiB per-file limit. No quota increase is required to land W3. The ~130 MiB figure is an estimate from the three measured platforms; the implementer should record the exact six-platform total on the first release, and request an increase later from real usage rather than a projection.

7. Workstreams

W1 — Deterministic runtime bundle (repo: vibe-show-runtime)

Two ordered parts. Part (a) is the substantive fix; (b) alone is insufficient.

(a) Pin the bundled dependency set. The staged package.json must resolve to the same dependency tree for a given source commit. Either commit a lockfile for the staged manifest and use npm ci, or replace the caret ranges with exact versions. Prefer the committed lockfile: it also pins transitive dependencies, which exact top-level versions do not.

(b) Create the archive deterministically, cross-platform. The build matrix runs on ubuntu-latest, ubuntu-24.04-arm, macos-15-intel, macos-15, windows-latest, and windows-11-arm. GNU-tar-only flags such as --sort=name --mtime=@0 --owner=0 --group=0 --numeric-owner work on the Ubuntu runners and fail on the macOS and Windows ones (bsdtar). Use a Node implementation instead — the tar npm package's portable: true option normalizes mtime/uid/gid and omits the gzip mtime header — with an explicitly sorted entry list. Record the new dependency in package.json (dependencies are never added silently).

Platform-native binaries still legitimately differ per platform; determinism is required per (platform, commit), not across platforms.

Acceptance: building the same commit twice on the same runner OS, in separate clean checkouts, produces byte-identical archives. Add this as a CI check.

W2 — Narrow the install identity (repo: avibe)

In core/show_runtime.py, remove the whole-manifest digest from both the fingerprint and the match check:

fingerprint = hashlib.sha256(
    f"{manifest.runtime_version}:{archive.platform}:{archive.sha256}".encode("utf-8")
).hexdigest()[:16]

and drop the manifest_sha256 comparison from _manifest_install_matches. Keep writing manifest_sha256 into the install metadata for diagnostics.

This loosens nothing: runtime_version, platform, and archive.sha256 all remain exact-equality gates. It only stops unrelated manifest content from participating in identity.

Migration: existing installs carry the old fingerprint in their directory name. _legacy_manifest_install_dir already establishes the precedent for tolerating a prior layout — extend the same treatment so an install that matches on the three retained fields is adopted in place rather than re-downloaded. This must not weaken _protected_archive_sha256s or _clean_manifest_install_dirs: an adopted install and its archive must be protected from GC.

Acceptance: a manifest edit confined to one platform leaves other platforms' installs valid. An install created by the previous fingerprint scheme is adopted without a download.

W3 — Multi-source archive delivery

Repos: avibe, vibe-show-runtime, plus a new avibe-show-runtime PyPI distribution. avibe-os stays a single py3-none-any wheel throughout.

Replace the one hard-coded github.com GET with an ordered ladder. Every tier either is local or is a registry a third party already mirrors in full:

Tier Source Weak-network reachability Work
1 avibe-show-runtime resolved as a dependency at install time Tsinghua and Aliyun mirror PyPI in full, and install.sh already walks that ladder for avibe-os itself W3.2
2 local downloads/<sha256>.tgz local exists
3 npm registry, then registry.npmmirror.com first-class China mirror, identical path layout W3.3
4 GitHub release asset poor — today's only tier exists

Tier 1 is what satisfies goal 1 ("a completed install implies a working Show Page"), and it needs no new infrastructure: pip resolves it through the same index, and the same mirror, that delivered avibe-os. Tiers 3 and 4 cover platforms tier 1 has no wheel for, sideloaded wheels, and installs that bypassed the index.

Ladder order in _resolve_manifest_archive is tier 2 → tier 1 → tier 3 → tier 4: both local tiers come first, and the already-materialized cache before the packaged copy so a hit costs no extraction.

W3.0 — Give the runtime a real version (repo: vibe-show-runtime)

Prerequisite for W3.2 and W3.3, and the reason the CDN option in §5 looked cheaper. Today @avibe/show-runtime, @avibe/show-ui, and @avibe/show-sdk are all "version": "0.0.0", and the commit SHA is the only identity — which neither PyPI nor npm will accept as a version.

Recommended scheme: date-based 0.<YYYYMMDD>.<n>, where n counts releases within the day. One string is simultaneously a valid PEP 440 version and valid semver, so PyPI and npm publish under the same version. The commit SHA stays the audit identity: it remains runtime_version in the manifest, and is recorded in both packages' metadata. The implementer confirms or replaces this scheme, and records the decision here.

Acceptance: a tagged runtime release produces one version string accepted by both registries, and the manifest for that release records both the version and the commit SHA.

W3.1 — Source ladder in the resolver (repo: avibe)

Restructure _resolve_manifest_archive into an ordered list of candidate sources with one shared contract per candidate:

  • verify the manifest's size and sha256 before the bytes are used;
  • on any failure — unreachable, corrupt, absent, checksum mismatch — log at warning with the source name and the reason, then fall through to the next candidate. Never fail closed on one bad source.
  • on success, materialize at downloads/<sha256>.tgz and record which source won in the install metadata, so a support question has an answer.

Only when every candidate has failed does the reason code propagate to W4/W5.

Inventory the existing VIBE_SHOW_RUNTIME_SOURCE implementations first — there are already four (manifest-cache, archive, github, npm) — and extend that machinery rather than adding a parallel path. Per the reuse ladder, generalizing _copy_packaged_runtime_archive is preferred over a new helper.

This PR is independently valuable: it removes the single point of failure using only tiers that exist today, before any new distribution is published.

Acceptance: with the GitHub host unreachable but npm reachable, a cold install obtains the archive. A deliberately corrupted candidate is skipped, not fatal, and the fallthrough is visible in the log.

W3.2 — avibe-show-runtime distribution (repos: vibe-show-runtime, avibe)

Layout. Per runtime version, publish six platform wheels — each carrying exactly one platform's Show Runtime archive — plus one py3-none-any wheel that carries no archive. Wheel-tag priority makes installers prefer the platform wheel; musl, BSD, and any future target resolve the pure wheel instead. That pure wheel is what keeps resolution from hard-failing on an unmatched platform: it installs successfully, contributes no archive, and the resolver falls through to tier 3. This is the same fallback-tier trick the rejected design used at the avibe-os level, relocated to where it costs nothing.

Platform tag mapping must be decided explicitly and recorded here by the implementer (darwin-arm64 → macosx_11_0_arm64, linux-x64 → manylinux_2_17_x86_64, win32-x64 → win_amd64, and so on), with the glibc floor chosen to match what the bundled native binaries actually require. This is the one piece of the rejected design that survives — but it lives in a small new project instead of in avibe's build hook.

Dependency. avibe-os declares avibe-show-runtime==<version> as an ordinary pinned dependency, with no environment markers: the pure fallback wheel makes markers unnecessary. Keep the pin a literal in pyproject.toml — do not generate it at build time — and add a CI check asserting it equals the version recorded in vibe/show_runtime_manifest.json. hatch_build.py already validates rather than generates; follow that precedent.

The pin is the mechanism that makes runtime/scaffold compatibility resolver-enforced instead of implicit in a manifest, which is what §5's rollback rejection is really asking for.

Resolution. Tier 1 reads importlib.resources.files("avibe_show_runtime") / <archive-name>, validates size and sha256, and on success copies to downloads/<sha256>.tgz. An ImportError or a missing file is an ordinary fallthrough, not an error — the pure wheel hits this path by design.

Pipeline. The existing assertion in publish.yml and release_ai.yml — that the avibe-os wheel contains no vibe/show_runtime/*.tgz — is correct and stays. Add the mirror-image checks in the runtime project: each platform wheel contains exactly its own platform's archive, with a sha256 equal to the manifest entry, and the pure wheel contains none.

Acceptance: on a supported platform, uv tool install avibe-os with all network egress blocked after installation yields a working Show Page with no download. On an unsupported platform the install still succeeds and degrades to tiers 3–4.

W3.3 — npm tier (repos: vibe-show-runtime, avibe)

Publish the per-platform archives to npm under @avibe/show-runtime-<platform>, following the established os/cpu-scoped pattern used by esbuild and swc.

One trap: npm re-tars on publish, so the registry tarball's own sha256 will not equal the manifest's archive.sha256. Carry our archive as a file inside the npm package and verify that inner file's sha256 after extraction. This needs no manifest schema change.

Mirroring is a base-URL swap — registry.npmjs.org → registry.npmmirror.com, identical path layout — expressed as an ordered list of base URLs with an env override, not as a new manifest field.

Acceptance: with registry.npmjs.org blackholed, the npmmirror base URL serves a verified archive.

W3.4 — Docs (repos: avibe, avibe-docs)

  • Correct the stale AGENTS.md §9 sentence. Under W3 there is nothing to bundle into a pre-release wheel; a GitHub-only pre-release resolves its runtime from the pinned avibe-show-runtime version, which in most cases is already published because the runtime cadence is ~3× slower than the release cadence.
  • Add a user-facing weak-network / offline install page to avibe-docs/ covering vibe doctor repair show-runtime, the source ladder and its env overrides, and the VIBE_SHOW_RUNTIME_ARCHIVE_PATH / _ARCHIVE_URL / _MANIFEST_PATH / _MANIFEST_URL / _OFFLINE and VIBE_INSTALL_SKIP_SHOW_RUNTIME escape hatches. Today avibe-docs/ mentions none of them. Keep English and Chinese in 1:1 correspondence.
  • VIBE_SHOW_RUNTIME_SOURCE=npm becomes documentable once W3.3 ships; it must stay undocumented until then, because @avibe/show-runtime is not on the public registry today.

W4 — Truthful recovery evidence; bounded retry deferred (repo: avibe)

PR #1640 attempted to replace a lifetime latch with bounded automatic retry. Nine reviewed implementation heads produced 28 findings and no clean pass. The retry identity, trigger policy, budget, record, disposition, and pre-probe mechanisms repeatedly generated fresh races and projection gaps. The review breaker therefore froze that design. PR #1640 deletes the retry machinery without replacement and keeps only the parts that converged: declared failure data, structured evidence, typed transport errors, and truthful manual recovery. Issue #1637 remains open for a separately designed bounded-retry change.

The retained rules are normative:

  1. No request-path health pre-probe. If _base_url is set, request() uses that snapshot directly. A transport-level failure with no HTTP response is the detector and invalidates that snapshot under the admission lock only while both its URL and tracked process still match, so a delayed failure from an old process cannot invalidate its replacement. The next request then re-enters admission. An HTTP response, including a 5xx response from the sidecar, proves transport succeeded and does not invalidate the runtime. No await may occur between reading _base_url and selecting it for the request.
  2. Owning operations normalize only operational I/O. Every command-resolution and runtime-metadata path converts OSError subclasses into typed failure evidence before returning to the UI, and request transport catches the specific httpx network exceptions it owns. Programming defects such as TypeError and AttributeError propagate unchanged. A malformed user command is input evidence, so command parsing converts it at the command-resolution boundary. Explicit-command resolution has one owner shared by startup admission, install preflight, and status. It returns an existing ShowRuntimeAvailability carrying either the resolved command or complete reason/class/action evidence. Only the explicit-configuration flag may mean "no override"; a parse failure may never be collapsed to None, because that would let status fall through to an unrelated managed provider and report a runtime that startup will refuse.
  3. Retry now renders its one expected page response. One click performs exactly one fetch. A direct 2xx HTML response is rendered into the current document from a private script scope, so repeated recovery-page renders cannot collide on top-level bindings. A redirect, non-2xx response, or non-HTML response is never treated as page content and instead returns control to normal browser navigation; in particular, expired credentials navigate to login rather than rendering a 401 JSON body. This corrects the earlier R7 rule, whose unconditional one-response rendering made authentication responses indistinguishable from page responses.

Install-lock contention remains not_applicable: another process owns progress, so this caller did not run a provider. Recovery remains request-driven; no background timer or automatic attempt budget exists in PR #1640.

Installed runtimes are resolved before mutation when installed evidence proves the selected input. Startup admission first projects the shared explicit-command owner when an override exists. Otherwise it reuses the in-memory managed command, then performs one offline, read-only lookup for manifest, GitHub source, and npm. A hit never enters provider installation. An absent runtime, force_install=True, or a remote manifest enters mutating admission. Archive is intentionally different: a configured local archive is new input, so the provider attempts publication first and falls back to the installed archive only when that attempt fails. The master regression test that replaces an old installed archive with a changed local archive is the contract guard. Archive URL downloads after a process restart are existing behavior tracked separately in issue #1657. This boundary is independent of the deleted retry machinery.

Failure classification is declared data and published by the evidence owner. Each (reason, provenance, retryable) key has one declaration carrying its dimension, owning artifact, class, and user ownership. Provenance and retryability are optional evidence discriminators; lookup prefers the fully measured key and falls back to a less-specific declaration, while an undeclared outcome remains unclassified and repairable. Classification and recovery action are total lookups over that declaration. A configured manifest and the packaged manifest may publish the same failure reason, but their provenance keeps the user's change-setting obligation distinct from repair of packaged bytes. The same rule applies to archives: a missing configured path is a user-owned setting error, while absent packaged bytes remain repairable. An AST census derives this set from every archive reason emitted under a positive self.archive_path guard and requires configured and packaged declarations for each one; declaration coverage is not a hand-written sibling list.

Download classification consumes the retryable fact already measured by dependency_error_details. A retryable manifest or archive failure remains transient and repairable. A non-retryable failure changes a setting only when its URL provenance is configured; the same failure against packaged or default release input remains repairable and makes no claim about user ownership. The evidence-key census derives every field stored by the shared download-error owner and requires each field either to participate in declaration selection or to appear once in the explicitly irrelevant set. This census failed on retryable before the field was plumbed, and it prevents a later discriminator from being silently dropped.

This is the final failure-classification fold change in PR #1640. Any later finding in this class is filed and handled in a follow-up PR rather than re-entering this branch. Install admission clears operation-local evidence before any provider runs, so a later I/O failure cannot inherit an earlier operation's reason, provenance, or download detail. A managed command that disappears is runtime evidence owned by the managed artifact and is not classified as a user configuration error; an explicit command failure remains configured. The page consumes the published class and action and never rebuilds either from a reason prefix or nearby state.

Every policy, install, and runtime payload is serialized by ShowRuntimeAvailability. Status may select which availability it reports, but it may not hand-build a partial dimension for one provider path. A module-wide AST census rejects any dimension-shaped dictionary outside the serializer, so improving one branch cannot leave its managed sibling on an older schema. Review attribution uses behavior rather than line blame: a hoist or extraction may re-blame unchanged bytes, so a head counts as introducing a finding only when the cited value or behavior differs from its predecessor.

Runtime transport is exception-closed for evidence. request() and request_global() share one manager-owned transport boundary. A transport exception publishes reason, class, and recovery action through ShowRuntimeUnavailableError; an explicit total deadline remains the distinct ShowRuntimeRequestTimeoutError. The UI catches only those typed outcomes. Its former fallback, which fabricated recovery facts for arbitrary exceptions, is deleted. Unknown programming errors stay loud instead of acquiring evidence no owner published.

Manual recovery is truthful and authorized. There are exactly three user obligations the page can present: run a repair, change a setting or prerequisite the owner controls, or accept that no local action can help. The recovery header requests an explicit action; it never grants authority. Only the authenticated instance owner is shown Retry now, while public and limited viewers receive a manual reload action they can perform themselves.

The freeze chose deletion over extraction because the seam crosses fields inside shared admission functions. Re-extracting the retained subset from master would rewrite the same regions that produced the findings while discarding the review history. Deleting the enumerated retry symbols is mechanically verifiable and introduces no replacement state machine, class, or module-level table. One late review finding was blamed to that deletion commit: its total status boundary converted a malformed explicit command to None and discarded the evidence needed to distinguish "not configured" from "configured incorrectly." The forward stop condition was not violated by that stock finding, but the record must not claim the deletion commit introduced zero defects.

Through one admission path. This requirement was missing from the first version of this spec, and its absence produced four review findings across two heads of PR #1634 — see the note below. "Three opportunities attempt installation" must not become three implementations. Exactly one manager-owned method admits an install, and it owns all four of:

  1. the opt-out policy (auto_install, VIBE_SHOW_RUNTIME_AUTO_INSTALL, VIBE_INSTALL_SKIP_SHOW_RUNTIME);
  2. serialization — one lock covering every provider, not just the manifest provider's _install_guard_locked;
  3. the failure classification and recovery evidence above;
  4. writing the resulting command into shared manager state, so a later caller reuses it instead of installing again.

prepare(), the startup reconcile, and the request path are callers of that method. None of them re-implements any of the four, and none of them reaches _install_managed_runtime directly.

A corollary the callers need: a startup reconcile result must distinguish the dependency outcome from whether prewarm is allowed. A runtime that was deliberately skipped is not a failure, but it is also not ready to prewarm, and one boolean cannot carry both. This falls out of having a single owner; it is not a separate fix.

One admission path is not enough; the admission outcome also needs one shape. PR #1634 consolidated the path and the same class reappeared on the next head at a different consumer, because ok still flattens three independent states into one boolean. Name them separately and let every consumer read the dimension it actually cares about:

  • policy — is installing allowed here at all, and if not, which knob said so. VIBE_SHOW_RUNTIME_AUTO_INSTALL=0 is an automatic-install opt-out; an explicit vibe runtime prepare is a direct user request and must not be blocked by it. Flattening these two is why the opt-out silently disabled the manual command.
  • install — installed, absent, or failed, carrying the transient/permanent/configured/checksum classification.
  • runtime — proven serving, not yet checked, or failed to start, carrying its own reason.

"Skipped by policy" is not "ready", and neither is "installed". vibe runtime prepare --strict must not report ready for a runtime that is merely not forbidden. Consumers — the CLI, startup reconcile, the prewarm gate, the /show/ request path, the recovery page payload, and vibe doctor — project from this value. None re-derives it, and none invents a local proxy for it.

The install dimension must be answerable from disk alone. Today it is not: _installed_manifest_runtime_command (core/show_runtime.py:1632) opens with _load_runtime_manifest() and returns None when that fails, and _load_runtime_manifest (:1865) fails for a remote manifest_url both when self.offline is set and when the download raises (runtime_manifest_unavailable_offline, runtime_manifest_download_failed). So a machine that merely cannot reach the manifest host right now reports its perfectly good on-disk runtime as absent — the original failure this document was written about, reappearing in the status surface. The coupling is not arbitrary: install directories are content-addressed on sha256(runtime_version:platform:archive_sha256), so without the manifest the code does not know which fingerprint to look for.

current.json already answers that question without the network — naming the last install is the reason it exists. One resolver owns "what is installed on disk", reading the pointer plus each install's .vibe-show-runtime.json, and fails closed unless the install_dir resolves safely under versions/, the provider/platform/source lineage matches, and the pointer agrees with the metadata on runtime version, platform, and archive digest. Not the whole-manifest digest: W2 deliberately narrowed the install identity to sha256(runtime_version:platform:archive_sha256) so that an edit to some other platform's manifest entry cannot invalidate a good install, and demanding manifest-digest equality here would reintroduce exactly that sensitivity. A manifest digest is validated for shape, never for equality. It establishes install = installed and nothing more; the runtime dimension stays unchecked until something proves the runtime serves. Policy skip and offline status both project from it. offline then means only "do not fetch", never "assume nothing is installed".

Policy inputs, decided once. The first version of this section said an explicit vibe runtime prepare must not be blocked by the auto-install opt-out and said nothing about the other knobs, which left force bypassing everything. The full space, so no row is left to inference:

Input Automatic preparation Explicit user command
VIBE_INSTALL_SKIP_SHOW_RUNTIME=1 skipped allowed
VIBE_SHOW_RUNTIME_AUTO_INSTALL=0 skipped allowed
neither set allowed allowed

force is orthogonal to every row: it decides whether an existing install is replaced, and never grants or removes authorization. Tests cover the whole table, not the one cell that produced a finding.

VIBE_INSTALL_SKIP_SHOW_RUNTIME does not block an explicit command, and that is a deliberate reading of what it is. It is consulted by install.sh:572, install.ps1:357, and vibe/upgrade.py, its own message calls it skipping "preparation", the e2e install and upgrade tests set it to avoid fetching ~21 MiB, and it appears nowhere in avibe-docs. It is a "do not do this on your own" flag — installer, upgrade, startup, prewarm, request-path auto-install — not a standing prohibition on the machine ever holding the runtime. Treating it as one would strand any environment that has it exported with no documented way to lift it. Both knobs are therefore the same policy class reached through different entry points; they differ in which automatic paths they cover, not in whether an explicit request overrides them. If a real "never, not even explicitly" policy is ever wanted, it needs its own documented knob, and refusing an explicit command must name the knob that refused and how to lift it.

Prerequisites are not policy. A missing node is an environment fact, so it reports as an install/runtime failure carrying runtime_node_missing, never as "skipped by policy" — folding it into the policy dimension would be the same flattening this section exists to prevent. Declining on a prerequisite is also not an attempt: it must not set the attempted flag, or the lifetime latch fires and the gate buys nothing.

Enumerate the consumers; do not wait to be shown the next one. This class has now been found four times — ok flattening three states, the recovery poll's page marker, the doctor verifier's URL marker, and manifest readability standing in for install state — each time at a consumer the previous round had not touched. Fixing them one at a time cannot terminate. The closing move is an inventory: list every reader of policy, install, and runtime state, and state per reader which dimension it consumes and that it derives none of them locally. A ruling that still leaves a consumer for the reviewer to discover is not the terminal rule.

State answers "what is"; an operation answers "what happened." The fifth instance of the class arrived from the opposite direction, so it is worth stating separately. Under a forced repair, when the replacement package fails to download or parse, the manifest, archive, and github providers all fall back to returning the previously installed command and clearing the install reason. Admission then reports ok, and every consumer of a forced prepare() infers from that proxy that the replacement it asked for completed: vibe doctor repair prints repaired, and the Web UI job at vibe/api.py:8424 prints "Show Runtime ready." Nothing was replaced.

No state snapshot can answer this question, because the state is identical whether replacement succeeded or failed and fell back; only the histories differ. So the fix is not a fourth dimension and not a new field beside ok — a second field a consumer may forget to read is the same proxy one column over. It is what ok means:

prepare() reports the outcome of the operation it was asked to perform, and force selects which operation that was: without it, "make the runtime available"; with it, "replace the install." ok is true only when that operation completed.

After a failed forced replacement two things are true at once and both are reported: the operation failed, and the old runtime is still installed and serving. That is what the split is for, not a contradiction needing a new concept. Falling back is a successful state outcome and a failed operation outcome, so the fallback path must stop erasing the reason. The reuse decision — "we hold an existing command; may we return it as this admission's success?" — is one table keyed on whether replacement was required and whether it completed, and it gets one owner that all four providers call. Three of the four had the same bug at three call sites, and W3.1 adds more sources to this ladder; a convention would not survive that.

The single owner must not take "did the replacement happen" as a declared input. The first attempt at this rule gave the owner the decision and left each provider to report replacement_completed, which is a free parameter and therefore not a terminal rule. The manifest and archive providers happen to be sound because their claim sits immediately after shutil.move: reaching that line is the replacement, so the claim is a structural consequence of the code position. npm's is not — it comes from a subprocess that decides for itself whether to do any work, and npm install on a satisfied tree does none, so a corrupt-but-satisfied package reports a completed replacement after touching nothing.

replacement_completed is sound only where reaching that line is itself the replacement. Where replacement is delegated to something that may choose to do nothing — a package manager, a build tool, a remote — the code makes it unconditional before delegating, so the claim becomes structural again.

npm therefore removes the managed package tree before installing under force, which is the discipline the github path already follows when it drops the build marker before npm ci so a failure leaves "unknown" rather than a stale truth. Every call site that passes this argument carries a one-line justification of why its line is the replacement; "the tool reported success" is the defect, not a justification. Destroying first creates its own obligation: a path that has already removed the old artifact converts every failure into a structured outcome, because raising past the owner leaves the caller unable to distinguish "nothing happened" from "the old runtime is gone."

Decide the operation outcome where nothing can get past it. Three rounds of this section's rules each inventoried one notch too narrowly — the consumers of an outcome, then the declarers of the evidence, then the call sites of the owner — and each asked what goes through the structure rather than what gets past it. The path that finally proved it is the explicit-command branch: with VIBE_SHOW_RUNTIME_BIN set, admission returns before force is ever read, so a forced prepare reports success having replaced nothing, and both Doctor and the Web UI job say the runtime is ready. Eight of the nine exits of _attempt_managed_install handle force correctly, including the install-guard contention branch that deliberately refuses to reuse a command under force. The ninth was written to answer "is there a command?" and was never revisited when force acquired meaning.

So the decision moves to admission, where every exit already publishes and no path can leave without doing so. _attempt_managed_install returns the state and the operation outcome as two values with no default on the operation, so a future exit cannot omit it; the provider-level helper becomes one contributor rather than the sole owner. State and operation still travel side by side, neither derived from the other, exactly as the payload keeps ok and status apart — the operation outcome does not join ShowRuntimeAvailability. The terminal inventory is therefore the exits of one function, a closed set a reader can enumerate, rather than the callers of a helper, where "it bypassed the owner" is expressible.

A forced replacement of a user-supplied command is not a failure; it is not applicable. Those bytes belong to whoever set the knob, so the operation is refused naming the knob, in the same shape this section already mandates for policy refusals, and the report says what is true: this runtime is a command you supplied, and it starts or it does not.

That refusal is named in the operation outcome, never in the state. The first attempt wrote policy_reason="VIBE_SHOW_RUNTIME_BIN" if force else None onto the published availability, which made the policy dimension a function of what the caller asked: the same machine reported policy ALLOWED to status() and policy SKIPPED to a forced prepare. It was not cosmetic, because prepare() reads that field to decide whether the status snapshot may touch the network (status_offline = True if policy is SKIPPED), so a forced prepare silently computed a different snapshot than an unforced one. The gating is right for the two real knobs and broke only because a force-dependent value landed in the field it reads — one proxy, two consumers, divergent answers, the same disease this section exists to close. Hence: the policy dimension is a function of configuration alone; if its value can change because the caller asked for something different, it is carrying operation history. Whether an explicit command should report as policy-skipped unconditionally is a separate and defensible question, but it changes what status prints for every such user on every call, so it belongs to its own change with its own copy rather than arriving as a byproduct.

The same rule, read backwards, governs the destructive direction. vibe doctor repair's startability check has three outcomes, not two — starts, does not start, could not be determined — and only the middle one authorizes replacement. An unproven precondition never authorizes a destructive action, so a machine that merely failed to create a temp workspace must not have its working runtime rmtree'd. The flattening was possible because the verifier returned a (result | None, error | None) tuple and each consumer re-derived meaning from result is None: two consumers forty lines apart, one fixed and one left to be found by the next review, which is the failure this section's consumer-inventory rule exists to prevent. The verifier returns one named outcome instead, so there is nothing to re-derive and every consumer branches exhaustively. "Could not determine" is never reported as runtime_start_failed; it carries runtime_start_verification_failed and its detail, because claiming a startup failure nobody observed is the same lie as claiming a replacement nobody performed.

The destructive transition is itself a boundary. Making replacement structural moved real destruction into the install path, and the code around it still assumed nothing is ever removed. The shipped boundary owns cache invalidation and delegate failures; authorization to move a developer-visible checkout leaves for the successor section below.

Invalidate before destroying. _managed_command is a manager-level cache read at seven sites as proof that installed bytes exist, including ensure()'s spawn fast path and the policy-skip publisher, and nothing cleared it when the new code removed the artifact it names. A forced replacement whose build then failed left the next unforced prepare() reporting installed and completed with a path to a file that no longer exists. The provider-local instance of this was already fixed by setting existing_command = None after removing the tree it resolves from; the cache is the same insight one level up, which is where every fix in this section has ended up. A cached path is not evidence of bytes: any state that stands in for the artifact is invalidated before the artifact is destroyed, not after the replacement is judged.

Successor: protect the managed GitHub checkout

The baseline this successor must replace is deliberately named rather than implied. Once the cheap build-marker short-circuit stops matching, master runs git checkout FETCH_HEAD without authorization. A developer with local commits in the managed checkout can therefore have them displaced by any /show/ request. Removing checkout ownership from 2b′ does not introduce that hazard because none of this work has merged, but it does leave the known pre-existing behavior unfixed. Protecting the managed checkout is the successor's headline; a three-valued decision type is the means, not the project.

Refuse rather than coerce. Deleting the build output proves the build wrote output; it says nothing about what the build was fed. git checkout FETCH_HEAD keeps local modifications to tracked files, and at the same revision it changes nothing at all, so a modified managed checkout can produce bytes attributed to the fetched revision. The remedy is not to force the tree back — that discards uncommitted work in a directory a developer may be editing, which is a supported source path, to make our own evidence claim true. --force authorizes replacing the install; it does not authorize discarding someone's edits, and a user asking for the first is not asking for the second. So contamination makes the forced replacement not applicable, refused with its own reason, the same shape as the explicit-command knob above — the third finding in this section resolved by declining an operation rather than performing a misreported one. The claim then holds in the remaining case: clean tree, at the fetched revision, output deleted, output resolves. Because a default that refuses is only safe if the ordinary path is clean, the check is measured against a normal clone-and-build before it ships, and narrowed to tracked modifications if build noise makes the broad check misfire. A caller who does want the destructive restore gets an explicit affordance with its own copy, never a silent widening of --force.

The authorization predicate took two more probes before it closed, and both are worth recording because the second one killed an appealing fix. A clean worktree can still hold commits the fetched revision does not contain, so porcelain-empty never meant "nothing here is the user's." The natural repair — require HEAD to be an ancestor of FETCH_HEAD — cannot work here: the managed checkout is created with clone --depth 1 and updated with fetch --depth 1, so the previous revision's parents sit behind the shallow graft and merge-base --is-ancestor returns false for the ordinary forward update, refusing exactly the case a forced repair exists to serve. Measured, not reasoned: a hermetic depth-1 clone at the previous revision with an empty porcelain returns rc=1. Ancestry is unavailable in this repository by construction, so the rule cannot be lineage-shaped. What is available is the same thing every terminal rule in this document rests on — data our own code wrote: Avibe records the revision it checked out, and HEAD equal to that record proves nothing was committed on top. A missing record is the genuinely undetermined case and must not strand checkouts made by older versions.

Scope note, because it decides the remedy: git checkout FETCH_HEAD from a clean tree deletes no commits. They remain reachable through the reflog, and through the branch ref when HEAD was on one; this checkout keeps HEAD detached, so committed work-in-progress becomes reflog-only and gc-eligible after the expiry window — recoverable for weeks, then gone. The evidence property is untouched either way, since a build attributed to FETCH_HEAD after a checkout is a true claim about FETCH_HEAD. So the obligation is to notice and refuse the forced path, not to manufacture a proof the repository cannot supply.

Two obligations come with a check whose default answer is refusal. It is measured against the real artifact, not against a fixture written to satisfy it — a test upstream given exactly the ignore rules the check needs proves the code reads its own input correctly and says nothing about whether the repository it will run against looks that way, so the premise is verified by cloning and building the real thing once and recording the output. And a refusal whose resolution belongs to the user names the place and the action, because it is the one failure in this path that nobody but the user can clear; reporting runtime_github_source_dirty through the generic prepare-failure copy hands them a machine token where the adjacent explicit-command refusal hands them the knob's name.

The guard belongs on the action, not on the mode. The seventh probe found the predicate correct and unreachable where it matters. It was consulted under if replacement_required and not self._github_source_allows_replacement(...), while git checkout FETCH_HEAD ran unconditionally — so the automatic path moved HEAD with no authorization at all, protected only by a cheap-path short-circuit that stops firing the moment upstream advances past the built revision. A developer with local commits in the managed checkout loses them to any /show/ request, which is the harm the forced path had just been taught to refuse, on the path taken far more often. The position was right and the condition was inherited from the iteration where the property was still called "forced replacement authorization." It is not: it is Avibe may take over this checkout, so every path that will move HEAD asks it. The answer differs by path, and refusing is wrong on the automatic one — it would stop serving the page over a workflow annoyance. Least harm there is to leave the checkout alone, build what is present, and record that the managed update was skipped, which on a machine where someone has committed local work is also the less surprising behavior.

Serving an unmanaged checkout is a fourth fact, and the first attempt to report it went through the flat top-level reason, which every consumer reads as "why the runtime is not available" — Doctor's failed branch, runtime.prepare.failed, and a status line printed whenever the field is non-empty. Measured on a healthy runtime: Installed: yes directly above Reason: runtime_github_source_revision_changed, with nothing anywhere saying the page is being served from the developer's commit. That is 2a's three-state contract violated one field further out, so the skip belongs in its own github_source.update and reason stays empty when nothing failed. Removing the leak owes the user the signal it was standing in for: status states that the runtime is serving a revision Avibe does not manage and names it, and prepare says it prepared but skipped the managed update instead of printing a bare success. This is the only surface where anyone finds out, so it is copy, not a token.

Evidence decides the verdict; the caller's mode may decide the remedy, never the verdict. The same commit that moved the guard onto the action also adopted an unverified revision as the managed baseline when the caller was not automatic — and an unverified revision is by definition the case where nothing establishes whose commit it is, so the adoption rests on who asked rather than on what is true. A legacy checkout holding local commits with a clean tree is indistinguishable from one sitting at an old upstream tip, and the first has its commits written into Avibe's record, after which the next forced repair is authorized to check them away. Mode-keyed authorization is the bug that paragraph fixed, reappearing one branch over, which is why the rule is stated as a separation rather than as another input: the predicate reads evidence only, and refuse-versus-skip is the caller's business. A checkout with no evidence is reported, not adopted; rejoining managed updates is the user's explicit act with its own copy, like the destructive-restore affordance above. The build marker stays unwritten on the skipped path, which costs a rebuild per process for that checkout — accepted, and not to be bought back with a marker that means two things.

A record written after the act it records can be false about our own action, and that is a different failure from an unproven one. When checkout FETCH_HEAD succeeded and persisting the revision did not, HEAD moved while the record stayed behind, so the next forced repair told the user to move or back up local commits they never made and to restore a revision they never chose. The harm is that false accusation, not the internal inconsistency, and it does not need atomicity to fix — it needs the record written first. Hold two values, the revision Avibe has committed to and the one it intends to move to; write the pending value before the checkout and refuse if that write fails, since nothing has moved yet; normalize to a single value after the checkout succeeds. Authorization is then a clean tree with HEAD at either value, and every window heals forward on the next run: a failed checkout leaves HEAD at the committed value, a crash before normalizing leaves it at the pending one, and both are authorized to proceed. Nothing is ever rolled back, so this stays a two-valued state rather than a journal and leaves W6's atomic switch untouched. One residual is accepted rather than handled: a checkout that dies after writing files but before moving HEAD leaves a genuinely dirty tree, so the dirty refusal fires first and says the directory has local changes, which is true and whose remedy works.

Reporting splits along the same seam. The update outcome travels in the update record and nowhere else — a failed or skipped managed update never reports as an install failure, because the install is whatever is on disk and it is fine. And the record on disk is the only source of truth: a successful read that finds no file means there is no skip, so the in-memory copy is a write-through cache that is never consulted as a fallback, which is a deletion rather than an added invalidation.

Then a mode branch got in front of that owner one more time. A refused takeover under a forced repair returned the operation failure without writing the record, so the one disk fact describing the refusal was missing and vibe runtime status kept showing an earlier attempt's target. The four other non-advancing exits in that function already write before they return, which is the tell: the code treats the record as unconditional and this branch simply preceded it. So the rule is positional and can be checked by reading — record the outcome above the mode branch; the mode branch holds only the remedy — and no helper is added, because the exits that already satisfy it are already in the right shape. The forced return keeps its own operation reason: the immediate operation did fail and the persisted update outcome was missing, two channels with two true statements, and collapsing them is the conflation this seam exists to prevent.

Three findings-bearing heads on a PR that changed a data model is a stop by itself, so the inventory was diagnosed rather than patched a third time. All three findings share one root: that function has seventeen exits, and each ruling here adds an invariant that must hold at every one of them, enforced only by whoever writes the next branch remembering. That is an enforcement gap, not a wrong record design — none of the three is evidence against the two-valued record. The remedy is therefore the positional move plus one parameterized case over every refusal reason in both modes, which turns the convention into coverage. Its fixture has to start from a source directory that already carries an older update record with a different target, because the harm named here is a stale record and a clean directory would let a loose assertion pass on the broken code. If a fourth head lands another exit-invariant violation, the remedy stops being a move and becomes one update-outcome owner that cannot be bypassed.

The fourth findings-bearing head exposed two remaining boundaries and closes this class with two rules whose enforcement is structural rather than conventional. First, an unknown revision is absence of evidence, not a value that may compare equal to another unknown. _git_revision failure becomes a structured source-update failure before any checkout-record comparison. Revision comparisons live only on the checkout-record type, whose authorization methods accept a proven string revision; callers do not compare revision or pending fields directly. This makes a normal stable record with pending = null incapable of authorizing an unreadable HEAD.

Second, checkout creation and ownership publication are one transition. Avibe clones into a same-parent staging directory, writes the schema-versioned ownership record inside that checkout, and only then renames the complete directory to source_dir. Therefore an Avibe-published source_dir is never externally reachable without its ownership evidence. Best-effort staging cleanup is hygiene rather than correctness: if cloning, revision inspection, record persistence, or publication fails, the final path was never exposed and the next attempt can retry without adopting or deleting an unverified checkout. Existing unverified directories remain user-owned evidence and are not mutated by a healing shortcut.

This is the final in-PR consolidation for checkout evidence and the destructive boundary. If a fifth findings-bearing head produces another instance of this class, the two-valued record model itself must be reconsidered; another exit guard is not an acceptable remedy.

The fifth head fired that tripwire, so the promise is discharged here: the two-valued record was reconsidered and the evidence exonerates it. No finding on any of five heads has been about revision / pending semantics. The tripwire fired on the wrong axis because it bounded an artifact — "the record" — when the property at risk was every piece of evidence about the checkout, wherever it is stored. A governance rule that names an artifact instead of a property is the same inadequate-proxy defect this document is about, one level up.

What head five actually showed is cheaper to state: each of its three findings is a rule already written above, applied at the site a reviewer named rather than owned by a module. An unowned rule buys exactly one more review round, so three unowned rules bought this one. The closing rules therefore name owners. Checkout evidence lives inside the checkout it describes, so a successful publish retires it by rename and no deletion is a transaction boundary. A dimension of state has no flat mirror beside its structured payload, so a consumer cannot reach a location without holding the state that makes the location meaningful. Artifact provenance is published from the build marker and cited from nowhere else, so a revision claim cannot be satisfied by checkout identity. Each remedy removes a mechanism or publishes an owner that already existed; none adds a branch.

New boundary, stated as a property rather than an artifact: a rule enters this document with the name of the module that makes violating it impossible. If a sixth head returns either a rule with no named owner or a payload field whose meaning depends on a sibling field, the update record and the status payload leave this PR and become their own change.

The sixth head fired that boundary. The persisted update record used state = "skipped" for both a known target that checkout takeover refused and a fetch or revision-inspection failure whose target might not exist. A consumer could interpret that field only by pairing it with reason and the nullable target_revision, so the state was another inadequate proxy. The record, its github_source.update status member, and the prepare/status copy leave this PR rather than acquiring a failure-specific consumer branch.

The install dimension stays. Its location is a different member of the status payload, its flat mirrors were removed on head five, and no later finding has implicated its owner or consumers. The checkout record, build-marker provenance, and operation outcome contract stay for the same reason: the sixth finding disproves none of them. This is a split by the property that recurred, not a rollback of adjacent owners that have held.

The follow-up starts from the reason the update record existed, not from its schema. Doctor can already report a failed managed update from the immediate operation reason, but an ordinary prepare may still succeed by reusing the old runtime and therefore clears that top-level failure. The record persisted that degraded side effect so a later status call could repeat it. That past event is not current state: vibe runtime status performs no network I/O and cannot know whether an update is available. The leading design is therefore for the operation to report its degraded side effect in band to the caller that just performed the fetch, while status makes no update claim it cannot verify. The follow-up may depart from that design only with a stated reason.

The next boundary is again a property: if a seventh findings-bearing head returns a finding against one of the remaining owners -- checkout evidence, the install dimension, build provenance, or the operation outcome contract -- that owner leaves this PR as its own change. Another site-level patch is not an acceptable remedy.

The reason this one predicate absorbed seven probes is worth naming even though it is out of scope here: one directory is both Avibe's build input and a place a developer may work, so every rule about it has to infer which role it is in. An eighth input would be another inference. If the predicate needs narrowing again, the answer is to stop conflating the two roles, not to add a term.

The seventh findings-bearing head fired that boundary, but on a different axis than the artifact and owner boundaries above. One two-valued type repeatedly carried a three-valued reality, and every consumer promoted "cannot determine" to one of the two definite answers:

Type Two represented values The third value it could not represent
ok: bool available / unavailable the requested operation did not run
raw revision / pending comparison equal / different neither revision is known
update state = "skipped" skipped / absent fetch never produced a target
takeover allowed: bool permitted / refused ownership could not be determined
install_dir beside installed present / absent intended, not achieved
current_revision used as provenance a revision / none checked out but never built

The governance boundary named the wrong axis twice. Head five bounded the update record when the property covered every piece of checkout evidence; head six bounded owners when the recurring risk lived in the two-valued type those owners shared. The seventh finding made the consequence concrete: a failed legacy ownership-record write returned allowed = false; the automatic consumer treated that as developer-owned, skipped the checkout, cleared the released build marker, and used the same boolean to decide not to restore it. One boolean gated both moving the checkout and destroying build evidence even though those actions have different safety conditions.

That gate and its ownership-record subgraph leave 2b′. The finding disappears with the gate: the retained path returns to master's unconditional build-marker restoration, so there is no site-level branch to patch. The successor takes the takeover decision, its consumers, and ownership-record transactionality. It starts with a named outcome of proven / refused / undetermined and structurally separates "may move this checkout" from "may destroy build evidence". Undetermined answers no to both. A write failure while adopting legacy evidence therefore returns the existing command untouched, preserves the marker, and recovers when permissions recover. Departing from that shape requires a stated reason.

2b′ keeps the install dimension, build-marker provenance, the operation outcome contract, provider replacement evidence, destructive cache invalidation and delegate failure normalization, and Doctor's first-install/reinstall copy split. These owners have drawn no finding for two heads, and 2c depends on the operation contract rather than checkout ownership. The successor may consume the shipped _github_install_attempt, generic update-failure reason, _git_revision, and _read_github_build_marker; those are one-way dependencies on retained contracts, not checkout ownership leaking back into 2b′.

Shipped in 2b′

One execution boundary for delegated work. The shared install-command helper already passed a five-minute timeout and let TimeoutExpired escape — someone decided a hung subprocess must not block forever and never decided what that means to the caller. Nonzero exit, spawn failure, and timeout are one thing to admission: the delegate did not produce a runtime. They collapse at the shared boundary, so every call site inherits it and no exception crosses admission from a path that has already destroyed state.

Note for expectation-setting: this fixes transient failures only. It would not have helped a user who cannot reach github.com at all; that is W3.

Acceptance: after a simulated download failure, a later /show/ request can try again and succeed, with no service restart. A forced repair whose replacement package fails reports the repair as failed with its real reason, reports the old runtime as still installed, and leaves it on disk; a startability check that cannot reach a verdict refuses the reinstall instead of performing it, and reports that it could not tell rather than that startup failed. A forced repair under the npm source does not report a completed replacement when the package tree was left untouched, and one whose install raises after the old tree was removed reports a structured failure rather than escaping. A forced repair of a runtime supplied through VIBE_SHOW_RUNTIME_BIN is refused naming that knob instead of reported as reinstalled. After a forced replacement whose build fails, a following unforced prepare() reports the runtime as absent rather than resolving a cached path to bytes that were removed; a forced repair against a locally modified managed checkout is refused naming the modification instead of overwriting it; and a delegated install that is killed by its own timeout is reported as a provider failure rather than escaping to the caller. And with upstream advanced past the built revision, an automatic /show/ request against a managed checkout carrying local commits leaves HEAD where it is and serves what is on disk, reporting the managed update as skipped in its own field and naming the served revision in user-facing output while the availability reason stays empty; and a checkout whose revision Avibe cannot verify is still refused after an unforced prepare rather than adopted as the managed baseline.

W5 — Tell the truth on failure (repo: avibe)

  • Thread the manager's reason into show_page_runtime_recovery_html and branch the copy on it. For an infrastructure failure, drop the src/App.tsx prompt and surface vibe doctor repair show-runtime.
  • Raise the /show/ failure logging from logger.debug to logger.warning and include the reason code.
  • Split SHOW_RUNTIME_RECOVERY_LOADING_DELAY_SECONDS into two constants: the page's loading-state delay and the node CLI's --fallback-delay-seconds.
  • Render a terminal failure immediately instead of after the 30 s delay.
  • Defer automatic polling to PR 2c′; PR 2c keeps a truthful manual recovery surface and an authenticated Retry-now action.

Recovery copy projects the user's obligation from published evidence. A repair command is shown only when local repair can address the failure; a deliberate policy opt-out names the setting to change; and an unsupported platform states that no local repair or retry changes the fact. The page never maps failure class to retry behavior. Install, runtime, and policy publish their recovery action inside their own dimensions, with no flat top-level mirror for a consumer to mispair.

All user-visible strings go through vibe/i18n/.

Prove readiness; do not accept a proxy for it. Two findings on PR #1634's third head were the same mistake in different places, and both are worth stating as a rule because the reduced signal looked adequate each time.

  • ensure() returns ShowRuntimeResult(True, base_url) as soon as _read_startup_url() yields a URL (core/show_runtime.py:306-311), with no health check — while the already-running path one screen above does call _healthy() before reporting available (:264). A runtime that prints its URL and immediately exits is therefore reported as available. Every consumer inherits this, including vibe doctor's repair verifier, which is what made it a finding here. A freshly started runtime must answer a request before it counts as serving.
  • Automatic recovery is deferred to PR 2c′. Until then the recovery page offers a manual reload plus an authenticated owner-only Retry-now action. PR 2c′ may poll only from a manager-owned admission signal, never from a browser counter. Its design remains open in #1637 rather than being implied by PR #1640.

The delivery record moves three resolved PR #1640 threads with that scope: polling state must survive document replacement, a failed browser fetch cannot consume manager-owned confirmation, and a terminal response cannot trigger another automatic Runtime request. Their resolution on PR #1640 records the split, not discharge of the behavior: the successor owns their consuming tests and exact-head close-out together with the manager-owned admission constraint above.

A probe proves only the state it was calibrated for. The first attempt at the fix above reused _healthy() exactly as the already-running path calls it: one request, connect=0.5s, read=2.0s, no retry. That budget was chosen for a runtime that has been serving for a while. Spending it on a process that started milliseconds ago is the same reduction one level down — the check is now in the right place and still is not evidence for the state it is asked about.

The asymmetry inside ensure() is the tell: _read_startup_url polls to a deadline because startup timing is unpredictable, and the readiness probe beside it got a single attempt. The cost of a false negative here is not a wrong status line — the branch calls self.stop(), so a runtime that was coming up fine is killed and the next request repeats the cycle. That is a self-inflicted startup loop on exactly the slow machines least able to absorb it, traded for the false positive being removed.

So: spawn-to-serving is one budget with one knob. The URL wait and the health wait share a single deadline rather than each owning one; two deadlines would double the worst case a page load waits through and invite the question of why they differ. Within that budget the runtime is proven by polling — retry until health answers, process.poll() goes non-None (fail immediately; catching this is the whole point), or the shared deadline expires. Each probe is bounded by the remaining budget, never by a constant of its own. If the total turns out to be too small for a cold start, it was already too small for the URL wait alone and gets raised once, in one place.

The current 10 s total budget is calibrated against a stronger runtime contract, not against Vite startup: the wrapper binds its HTTP listener before printing Vibe Show Runtime listening at ..., and handles GET /health directly before any session or Vite path. At vibe-show-runtime revision f40ac354e, a real spawn in a fresh workspace with no Vite cache printed the URL in 167.2 ms and answered /health in 171.3 ms on Node 22.18.0. The 30 s recovery-page fallback delay is a separate UI budget and is not on this readiness path. W1 must preserve the direct health contract; if a future bundle makes /health depend on Vite, the single startup budget must be remeasured and raised in the same change.

Distinguish the outcomes at the source: startup URL never appeared, process absent or exited, health never answered within the budget. All three are transient start failures and may share user-facing copy, but the codes stay distinct — this is the only place that information exists, and W4's retry work cannot reconstruct a distinction discarded here.

An identity travels with the thing it identifies; consumers project, never pair. dependencies_status() built the Settings row by taking installed from disk and version from the selected manifest, so a runtime installed at A while the wheel selects B renders as "B installed and ready" — a version that is on no disk anywhere. This is the same defect as the two above, arriving through a different door: not a proxy substituted for evidence, but two dimensions' answers stapled together by the consumer. The manager already owns the comparison (status() returns installed_matches_manifest), so the fix is that the installed identity ships inside the install dimension that owns it and the consumer reads rather than computes. Not as a top-level sibling of installed: a sibling is two adjacent keys any future consumer can pair the same wrong way, which is the hazard rather than the fix.

The reporting shape is settled by W4's ruling on the skipped GitHub update: a stale runtime works, so availability stays true, the displayed version is the installed one, and the pending update gets its own field and its own copy. The dependency schema already carries that vocabulary — version / latest_version / has_update, used correctly by the askill entry — so this is a reuse, not a new field.

One trap in that reuse. installed_matches_manifest is only ever set in the manifest branch; for the archive, github, and npm sources it is unconditionally false. Deriving has_update from it would announce a pending update on every GitHub-source dev checkout. The boolean is itself a two-valued proxy for a three-valued state — matches, differs, not comparable — which is this document's own root cause one level down, so it has to be able to say "not comparable". And the consumer must not recompute the answer by comparing version strings: _manifest_install_matches compares platform, digest, and candidate layout as well, so a string comparison would quietly disagree with the manager it is reporting for.

The same mispairing sits in core/managed_runtime.py's shared status() ("installed": binary is not None beside "version": manifest.runtime_version), inherited by the git, memory, and model-hub runtimes, and is repeated downstream in the memory-runtime dependency row. Show Runtime has its own status implementation and can be correct without touching that base, so those sites are recorded against the codebase-wide audit rather than pulled into this PR.

Acceptance: with the runtime unavailable, the page states the real reason within a second, updates when the reason changes, and recovers on its own after a successful repair. A runtime that starts and immediately exits is reported as failed, never as ready. A runtime that is slow but healthy within the startup budget is reported as ready, and is never killed for being slow. A runtime installed at one version while the wheel selects another reports the installed version with an explicit pending update, and no surface ever renders a version that is not on disk as installed.

W6 — Make the switch atomic (repo: avibe)

Obtain and verify the new archive before the new identity becomes authoritative, so a failed update leaves the working install in service rather than abandoning it. Sequence after W1–W3 so it is not compensating for churn that no longer exists.

W6 also owns a second, sharper case, found while reviewing PR #1634. Install and install are serialized — _install_guard_locked is a threading.RLock plus a MigrationFileLock, so it holds across processes, including a separately invoked vibe doctor. Install and running runtime are not. The archive is staged into a temp directory, but the final swap is shutil.rmtree(install_dir) then shutil.move(tmp_dir, install_dir) (core/show_runtime.py:1850 and :2148), and the install directory is content-addressed on sha256(runtime_version:platform:archive_sha256). A forced reinstall of the same runtime version and platform therefore resolves to the same path and deletes the directory a live runtime process is serving from. Identical-identity forced reinstalls are the exposure, and the archive, github, and npm providers modify in place as well.

A later review of PR #1634 reached the same exposure through a second door and made two corrections to the paragraph above. The first: it is not only a running process that loses its bytes. _resolve_managed_availability returns a cached _managed_command before it ever enters the install owner, and the same shape repeats at every cached and disk-reuse exit for all four sources, so a request can select a command and be about to spawn it while the forced path deletes the directory that command names. The second correction is that distinct-identity installs are not safe either, once pruning is counted: the prebuilt-* / manifest-* glob removal and _clean_manifest_install_dirs can delete an older versioned directory a cached command still points at, and keep_previous bounds retention by count rather than by reference. The atomic swap alone therefore does not close this; W6 owes retention bounded by reference.

The obvious remedy — extend the install lock to cover command selection — was considered and rejected, because no sound boundary for it exists. A critical section that ends at spawn does not protect the process: the runtime require()s modules lazily for its entire lifetime, so the bytes it has not read yet can still be deleted underneath it. A critical section that covers the runtime's lifetime over-serializes every request behind a long-lived server. Every choice of boundary is either unsound or unacceptable, and a rule whose free parameter an adversary can keep probing is not the terminal rule. The terminal rule removes the destruction instead: replacement creates and never overwrites, and a path that has been handed out to a command is never destroyed while anything can still reference it. Mutual exclusion between use and replacement then becomes unnecessary rather than carefully bounded, because the two never address the same bytes. Install-versus-install serialization is untouched: it remains necessary and sufficient for what it owns.

Until W6 lands, the mitigation is that no caller forces a reinstall without evidence the install is broken: vibe doctor repair show-runtime verifies startability first — in an isolated temp workspace and runtime, so the check itself cannot disturb the service — and reinstalls only when that check fails. W6 removes the reliance by making the swap atomic, at which point the gate is an optimization rather than a safety property. Any new forced-reinstall caller added before W6 must carry the same gate.

That mitigation is currently claimed rather than held, which is worse than not claiming it. The Settings dependencies page has an Install button for show-runtime, and it reaches prepare(force=True) through _prepare_show_runtime_job with no startability check at all — a user with a perfectly healthy runtime can delete the directory it is serving from by pressing it. The motive was manufactured one thread earlier: while that row paired the selected manifest's version with a disk install at a different version, it read as "B installed" on a machine running A, which is exactly what makes someone press Install on something that works. The two findings are one incident seen from both ends, and fixing the row removes the motive without removing the exposure. The remedy is not a second copy of Doctor's gate — one verified-repair path owned in one place, reached by both Doctor and Settings, so that a forced-reinstall caller cannot be written without the gate. That is a consolidation and belongs with W6 rather than bolted onto a merge-ready PR; it blocks W6, not the merge, because the exposure predates these PRs and shipping the truthful row strictly reduces it.

8. PR split

PR Scope Repo Notes
1 W2 avibe Small, surgical, unit-testable. Start here.
2a W4 admission outcome avibe The policy/install/runtime contract and every consumer projecting from it.
2b W5 readiness proof avibe ensure() health-probes a fresh start; doctor inherits it. Independent of 2a. Bounded retry plus Doctor's three-state startability; claims nothing about replacement.
2b′ W4 replacement operation contract avibe What prepare() claims, what a provider must prove, install-state ownership, build provenance, and destructive cache/delegate boundaries. Split out of 2b after six findings-bearing heads; checkout ownership is not shipped here.
2b″ Protect the managed GitHub checkout avibe Replace master's unconditional checkout takeover with a three-valued decision that keeps undetermined ownership away from both checkout movement and build-evidence destruction.
2c W4 evidence + W5 page avibe Declared failure classification, typed transport evidence, operational-I/O normalization, and an honest manual recovery page. Retry ownership was frozen and deleted.
2c′ Bounded automatic recovery avibe Open issue #1637. Design the bound separately before reintroducing any automatic poller or retry state.
3 W1 vibe-show-runtime Independent; effect appears at the next runtime release.
4 W3.1 avibe Source ladder. Valuable on its own — removes the single point of failure using only tiers that exist today.
5 W3.0 vibe-show-runtime Version scheme. Prerequisite for 6 and 7. Gate on owner confirmation.
6 W3.2 vibe-show-runtime + avibe New distribution and the pinned dependency. Release engineering.
7 W3.3 vibe-show-runtime + avibe npm tier and its mirror.
8 W3.4 avibe + avibe-docs Docs; can land alongside 6.
9 W6 avibe After all of the above.

PRs 1–4 need no new published artifact and no owner decision beyond this plan. The gate is before PR 5, because W3.0 fixes a version scheme into two public registries and is expensive to change afterwards.

PR 2 was originally one PR carrying all of W4 and W5. It produced three findings-bearing heads without a clean pass, and each round returned findings in the same three classes — admission outcome, readiness proof, recovery reporting — at a consumer the previous round had not touched. The recurrence was a symptom of the unit, not of the patches: a PR that owns three cross-cutting properties can always be shown a fourth consumer of whichever one is still reduced to a proxy. Hence the split above, one property per PR, each reviewable in a single pass. This is a lesson about sizing a PR by property count rather than by line count.

2b then split a second time, for a different reason worth distinguishing. It was not carrying two properties: every finding after the first two belonged to one property, the operation contract. What it was carrying was a property whose specification was still moving. Six findings-bearing heads each returned the same class at a boundary the previous round had not reached — providers, then the shared helper, then admission, then the destructive transition, then the authorization predicate twice — and each fix was correct at the level it was made. The signal is not "this PR owns too much" but "this contract is not finished being discovered," and the remedy is different: finished work stops waiting on it. Hence the readiness proof lands alone and the contract continues in 2b′.

2b′ then tripped the breaker on its own first implementation head, and that one did not split, which is the distinction the previous paragraph earns. Five findings landed at once, and none of them narrowed the predicate: one was a deletion restoring an evidence rule an earlier head already had, one was transactionality, and three were the same reporting seam. A predicate that is being unwound rather than narrowed is finished being discovered, so the remedy was consolidation inside the PR — one owner for the reporting seam, one for the checkout transition — not another handoff. The terminating condition was recorded with the decision: the predicate takes no new inputs and the record takes no new fields, and if either needs one more, the answer is the role separation and it becomes its own PR. A breaker trip asks which of those two the evidence supports; it does not answer.

The orchestration rule that produced this, recorded because it was nearly reasoned away: the trigger was registered while three PRs already sat unmerged, so the argument that a split frees nothing while the queue is stalled was already known when the commitment was made and could not later justify overriding it. A pre-commitment that yields to a fact available at the time it was made is not a rule.

9. Verification

Hermetic unit tests under tests/, extending tests/test_show_runtime_*.py and tests/test_ui_show_pages.py. Every test redirects the entire call path to test-owned state; none may read or write the real ~/.avibe.

  • W2: platform-scoped manifest edit does not invalidate other platforms; legacy-fingerprint install is adopted; GC still protects the adopted install and its archive.
  • W3.1: ladder order is honored; every candidate verifies size and sha256 before use; a corrupt or unreachable candidate falls through to the next rather than failing the install; the winning source is recorded in install metadata; the reason code only propagates once every candidate has failed.
  • W3.2: the packaged archive is preferred over any network tier; an absent avibe_show_runtime import and a missing archive inside it are both ordinary fallthroughs; a size/sha256 mismatch falls through; the avibe-os pin matches the manifest's recorded distribution version.
  • W3.3: the npm tarball's outer sha256 is not used for verification; the inner archive is verified after extraction; the mirror base URL is used when the primary registry is unreachable.
  • W4: owner-published failure classification; typed transport evidence; one-fetch explicit recovery; failed replacement remains independent from runtime usability; local I/O is normalized into typed evidence. Bounded retry remains open in #1637.
  • W5: reason-specific copy; terminal failures render immediately; i18n coverage.

Pipeline tests: extend tests/test_show_runtime_manifest_packaging.py with the pin-versus-manifest consistency check. The existing assertion that the avibe-os wheel carries no archives stays as written. Per-platform wheel content assertions belong in the runtime project.

Local Incus regression (local only, per AGENTS.md §3): cut network, restart, and expect an honest, specific error rather than a spinner. Restore network and refresh without restarting; expect automatic recovery. Then block github.com only, leaving npm reachable, and expect a cold install to succeed via tier 3. Finally, install with the runtime distribution present and block all egress afterwards; expect a working Show Page with no download.

10. Risks and open questions

  • PyPI quota. No increase needed (§6). Both distributions stay inside the default 10 GiB, and the largest file is ~22 MiB against a 100 MiB limit. Re-measure after the first three runtime releases and request an increase from real usage if the estimate proves low.
  • glibc floor for the manylinux tag. Determined by the bundled native binaries; must be measured, not assumed. Now scoped to the runtime distribution rather than to avibe's build hook.
  • Mirror sync lag. Tsinghua and Aliyun mirror PyPI on a schedule, so a freshly published runtime version can be briefly unresolvable for mirror-only users. Tiers 3 and 4 cover the window; publishing the runtime version before the avibe-os release that pins it shrinks it. This is the same ordering rule AGENTS.md §9 already imposes on manifest assets.
  • Version scheme is expensive to change. W3.0 fixes a version string into two public registries. This is the reason PR 5 is the gated one.
  • Two distributions must stay consistent. A published avibe-os whose pin names an unpublished runtime version is broken for every fresh install. The CI pin check catches the mismatch at build time; release ordering must publish the runtime first.
  • Pre-release channel convention. AGENTS.md §9 describes GitHub-only pre-releases, but 3.0.13rc1 is on PyPI. Reconcile the stated convention with actual practice while editing §9 in W3.4 — under W3 a pre-release must be able to resolve its pinned runtime, so which index it publishes to now matters.
  • Cross-OS determinism in W1. Windows path separators and case handling are the likely sources of residual nondeterminism; the CI double-build check is the guard.
  • Non-default sources still float. _RUNTIME_GITHUB_REF = "main" and releases/latest/download remain unpinned. Not addressed here; worth a follow-up so all sources share the pinned semantics.
  • Manifest mirrors. W3.1 and W3.3 express the ladder and its mirrors in code, which needs no change to the manifest schema shared by all five managed runtimes. Adding a mirrors: [] array to that schema (already schema_version: 1) stays deferred, not rejected — it is the mechanism a self-hosted origin tier (§5) would use if one is ever wanted, and it is safe because archives are sha256-verified.
  • Generalizing to the other managed runtimes. git and tmux share the manifest pattern and the same single-source exposure, and together add only ~2.5 MiB per platform. Deliberately out of scope here to keep the first distribution small; the mechanism generalizes and this is worth a follow-up.