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.

40.5 KB
Raw Blame

Show Runtime Install Convergence Contract

Status: bounded migration contract

Scope: analysis and design only; no production implementation

Code baseline: 2c6fcbe88 (origin/master when the install audit was revalidated on 2026-08-23). The original function-span measurement was made at 903414cc4. The GitHub source provider is assumed gone before migration.

Decision And Boundary

core/managed_runtime.py is the target owner of declarative manifest installation for git, Memory, model-hub, Show's manifest provider, and tmux. Show and tmux remain product adapters. Show keeps policy/install/serving projection, the system Node prerequisite and command. Memory keeps its explicit development provider and its controller-coordinated activation boundary. Tmux keeps macOS preparation and its runtime compatibility projection. At the measured baseline, direct-archive persists no install metadata and npm acquires no archive, so neither can supply the admitted-disk-record model. Their final ownership awaits the W3 source-ladder decision; this contract does not assume either delegates to the shared layer. Show serving (request proxying, lifecycle, readiness, prewarm, WebSocket routing, context capability, and stop) is outside this migration.

The validation boundary is intentionally finite. This document specifies the in-flight Step 1, records current behavior measured at named revisions, and defines only an intent and a gate for Steps 2-7. Their detailed contracts are written after the preceding step lands and its resulting code can be measured. Forecasts are planning history, not acceptance criteria.

Per-Function Verdict And Drift Ledger

This table is a non-normative audit census measured at 2c6fcbe88. Subset means delete Show's copy and call shared code. Superset means adopt shared code and extend the named general seam. Different means a product requirement keeps a Show adapter while common mechanics move underneath it. Every one-sided behavior is classified as a deliberate Show requirement or a latent defect in the side that lacks it.

Pair Verdict One-sided behavior and classification Measured at
status Different: shared installed snapshot plus Show projection. Show requirement: policy/install/serving dimensions, Node, and provider dispatch. Shared defect: selected-manifest failure hides a persisted install and can pair selected version with disk state. Show defect: inspection failure can be projected as absence. 2c6fcbe88
probe_archive_reachability Superset: shared manifest probe plus Show provider/reason adapter. Show requirement: direct archive, npm, and Show reason vocabulary. Shared already handles file: URLs. 2c6fcbe88
_clean_locked Superset: shared retention planner with legacy-layout and staging-pattern data. Show requirement: released layouts and source lineages. Shared defect: no archive reclamation or post-install retention. Show defect: glob-based discovery can suppress inspection errors. 2c6fcbe88
_preview_busy_reason Superset: shared preview with typed contention/inspection result and staging patterns. Shared defect: contention and an uninspectable/replaced guard share one reason. Show defect: absent-lock planning does not retain its process lock. 2c6fcbe88
_windows_preview_busy_reason Superset: shared Windows path-identity/reparse check. Shared defect: weaker Windows identity check and collapsed failure reason. Show requirement: only staging names differ. 2c6fcbe88
_resolve_manifest_archive Superset: shared content-addressed cache plus offline/provenance result data. Shared defect: archive-name caching grows without bound. Show requirement: provenance drives recovery reporting. Show defect: the cache fast path accepts any existing filesystem entry. 2c6fcbe88
_safe_extract_tar / safe_extract_tar Superset: shared composite-artifact extraction policy, defaulting to binary-strict. Show requirement: released Unix bundles contain internal links. Migration blocker: shared safely rejects all links today; removing that restriction without link-target confinement would create a defect. Shared defect: its version gate skips an available backported data filter on supported Python patch releases. 2c6fcbe88; archives v3.0.13
_runtime_platform_tag / runtime_platform_tag Subset. No behavioral difference. 2c6fcbe88
clean Superset: shared cleanup plus Show report adapter. Shared defect: downloaded archives are omitted. Show requirement: CLI/Doctor payload. Show defect: part of real cleanup occurs before the install guard. 2c6fcbe88
_write_manifest_install_metadata Different: shared atomic persistence plus a Show legacy-shape adapter. Show requirement: released directory-artifact metadata lacks binary fields and uses a Show filename/provider. Show defect: direct non-atomic write and no persisted Node prerequisite. 2c6fcbe88
_preview_lock_probe Superset: typed failure and reparse predicate in shared code. Shared defect: special/uninspectable paths are mislabeled as contention. 2c6fcbe88
_preview_guard Subset. Show defect: absent-descriptor planning loses process exclusion; shared retains it. 2c6fcbe88
_guard_path_matches_fd Superset: shared cross-platform exclusive-regular-file predicate. Shared defect: Windows reparse attributes are absent from its identity check. 2c6fcbe88
_release_preview_guard Subset. Show defect: the absent-descriptor branch has no retained process lock to release. 2c6fcbe88
_manifest_status_payload Superset: shared installed facts plus Show Node/platform projection. Show requirement: Node compatibility and complete Show platform diagnostics. Show defect: released metadata cannot provide offline minimum_node. 2c6fcbe88
_manifest_install_dir Superset: shared platform-artifact identity plus legacy candidates. Shared defect: whole-manifest digest changes reinstall unchanged host bytes. Show already uses platform-artifact identity. 2c6fcbe88
_archive_status_payload Subset: shared projection omits binary-only fields for directory artifacts. No missing Show behavior; shared binary fields apply only to strict binaries. 2c6fcbe88
_preview_raced_busy Superset: shared race check with declarative staging patterns. Shared defect: a new staging path is ignored when the lock path is absent or replaced. 2c6fcbe88
_downloaded_archive_matches Subset. No semantic difference beyond helper and reason names. 2c6fcbe88
_preview_lock_missing Subset. No semantic difference beyond the guard-path attribute name. 2c6fcbe88
_manifest_archive_for_platform Subset. Shared also supports aliases; Show's released manifest uses host tags, so this is neither a Show requirement nor a defect. 2c6fcbe88
_file_sha256 / file_sha256 Subset. No behavioral difference. 2c6fcbe88
_env_flag_enabled / env_flag_enabled Subset: use the shared truthy set. Show defect: arbitrary non-false text enables policy; repository callers document 1/true. 2c6fcbe88
_safe_path_part / safe_path_part Subset: shared sanitizer for new paths, metadata discovery for legacy paths. Show defect: ./.. survive and invalid characters use a weaker mapping. 2c6fcbe88

Shared-Layer Defects Exposed By Drift

These are the separately enumerated low-cost wins in the existing shared consumers. They are current-behavior findings, not issue filings. The rows are non-normative and measured at 2c6fcbe88.

Defect in shared Affected existing consumers Measured consequence Measured at
Manifest-gated installed state git, Memory, model-hub status() and resolve_binary() can forget an admitted disk install when no installable manifest is available. 2c6fcbe88
Selected identity reported as installed identity git, Memory, model-hub Status can publish the manifest version beside disk-derived installed state. 2c6fcbe88
Whole-manifest target identity git, Memory, model-hub; claim consequence in model-hub An unrelated platform edit changes the install directory; released model-hub claims can report install_target_changed. 2c6fcbe88
Mutation lock follows/under-validates its path git, Memory, model-hub Shared locking lacks Show's no-follow, link-count, and post-open path-identity checks. 2c6fcbe88
Preview collapses failure causes git, Memory, model-hub Special, replaced, or unreadable guard paths look like live contention; Windows reparse identity is weaker. 2c6fcbe88
No downloaded-archive retention git, Memory, model-hub Versioned downloads accumulate indefinitely. 2c6fcbe88
No post-success version retention git, Memory, model-hub ensure() never invokes existing version cleanup; Memory and model-hub have no equivalent user cleanup path. 2c6fcbe88
Version-gated tar data filter git, Memory, model-hub; also tmux Shared and tmux skip the backported filter on Python 3.10.12+ and 3.11.4+; their existing whitelist/path checks still apply. 2c6fcbe88

Shared link rejection is not a present vulnerability: it is a Step 3 capability gap. Four of Show's six archives cannot use the shared extractor until link support and confinement arrive together.

Uncounterparted Install Code

This non-normative census preserves the supplied 1,621-line Show grouping. Rows were measured at 903414cc4 and revalidated for install-side changes at 2c6fcbe88. Classification follows behavior, so mixed groups have more than one destination without double-counting their supplied line total.

Supplied group Lines Classification and destination Measured at
Manifest handling 421 Shared capability grows: source/cache handling, platform-artifact identity, installed-state reading, persistence, and legacy adoption benefit all five. Show manifest duplicates become dead after cutover. Show retains only product projection. 903414cc4; revalidated 2c6fcbe88
Archive cache / cleanup / protection 355 Shared capability grows: content-addressed downloads, protected-set discovery, cleanup reporting, and post-install retention benefit all five. The expectation is confirmed; Show CLI/Doctor wording remains product-specific. 903414cc4; revalidated 2c6fcbe88
Install lock and concurrency guard 221 Shared capability grows: mutation/preview exclusion and safe path identity benefit all five. Duplicate Show guard code and the duplicate exception branch become dead. 903414cc4; revalidated 2c6fcbe88
Install orchestration 195 Mixed: shared manifest transaction benefits Show/tmux; Show-specific policy, providers, availability, and operation outcomes remain. Duplicate manifest orchestration becomes dead. 903414cc4; revalidated 2c6fcbe88
Archive handling 120 Mixed: shared extraction/materialization grows for Show/tmux; the unpinned direct-archive source remains Show-specific because it is an operator escape hatch outside manifest integrity. Duplicate primitives become dead. 903414cc4; revalidated 2c6fcbe88
GitHub provider 104 Dead: removed by the prerequisite lane; no compatibility path is retained. 903414cc4; assumed removed
Status reporting 89 Mixed: shared disk-installed facts benefit all five; Show keeps policy/install/serving, provider, and Node projection. Duplicate filesystem inspection becomes dead. 903414cc4; revalidated 2c6fcbe88
Node version checking 61 Show-specific: Show executes a JavaScript directory artifact through system Node and enforces its runtime prerequisite. 903414cc4; revalidated 2c6fcbe88
npm provider 37 Show-specific: an explicit operator provider outside the pinned manifest transaction. 903414cc4; revalidated 2c6fcbe88
Other 18 Shared/dead: common redaction, errors, hashing, tagging, env parsing, and sanitizing already have shared owners; Show wrappers disappear. 903414cc4; revalidated 2c6fcbe88

Tmux is a separately measured 699-line outlier at 2c6fcbe88; it was not part of the supplied 1,621-line Show grouping. It independently owns manifest, archive, extraction, transaction/persistence, guard, and status mechanics, but not retention. Its macOS preparation, runnable/compatibility checks, utf8proc, and terminfo behavior remain product concerns.

Measured Current-Behavior Census

This section is non-normative. Each row is a falsifiable observation at its named revision, not a promise about a future implementation.

Current fact Observation Measured at
Step 1: Shared disk readers status() loads a manifest first, and resolve_binary() returns None before disk resolution when the manifest is unavailable or not installable. 2c6fcbe88
Step 1: Released model-hub claims install-state.json schemas 1 and 2 persist a target containing manifest_sha256; recovery compares that target. 2c6fcbe88
Record discrimination Current metadata/current-pointer writers persist no record_schema_version; released records are therefore unversioned, and field absence carries no record-generation information for a future schema change. 2c6fcbe88
Step 1: Memory development provider Presence of AVIBE_MEMORY_DEV_RUNTIME selects the development branch before managed state. A missing or incompatible configured interpreter returns the development-provider failure and does not fall through to a managed pointer or manifest. 2c6fcbe88
Step 1: Memory activation Memory overrides pointer writing; with a live provider root it fails closed without the controller coordinator, which receives candidate, root state, commit, and rollback callbacks. 2c6fcbe88; rechecked on master 2026-08-23
Step 1: Memory admission A released active pointer without admission_revision reruns the runtime compatibility probe. Success admits it; a false result or raised inspection rejects it rather than trusting shared binary metadata. 2c6fcbe88
Step 1: Disk-pointer confinement asymmetry Baseline shared _current_install_dir() resolves install_dir and checks only that the versions root is a parent; the in-flight shared reader adds absolute and strict resolution, rejects the versions root itself, and requires the binary beneath install_dir. Memory already adds regular-file and X_OK checks. 2c6fcbe88; Step 1 diff checked 2026-08-23
Step 1: Unreadable manifest labels A configured-local read_bytes OSError is manifest_missing in shared and invalid in Show; shared offline-cache read failure is manifest_unavailable_offline. 2c6fcbe88
Show prerequisite identity Show install matching compares runtime version, platform, and archive SHA-256, but not minimum_node; old metadata continues to supply the old prerequisite after a prerequisite-only manifest edit. 2c6fcbe88
Tmux schema 1 admission _verified_manifest_binary checks metadata and _tmux_binary_runnable; the runnable check accepts any non-empty tmux -V result and does not compare it with manifest tmux_version. 2c6fcbe88
Tmux byte phases Source-leaf verification occurs before preparation; macOS ad-hoc signing can change the installed binary bytes afterward. 2c6fcbe88
Step 1: Online unrelated-platform edit _manifest_install_dir() hashes the whole manifest digest with the selected archive digest. An online manifest edit for another platform therefore selects a new directory even when this host's archive bytes are unchanged. 2c6fcbe88
Step 1: Model-hub platform alias Model-hub maps host linux-x64 to released artifact label linux-amd64; its released pointer, metadata, and claim can therefore carry a label different from the host tag. 2c6fcbe88
Step 4: Downloads namespace Remote manifest caches use downloads/manifest-<digest>.json beside archives, so the namespace mixes durable manifest facts with disposable archive bytes. 2c6fcbe88
Step 4: Retention with a readable pointer Shared and Show both protect the pointer's install unconditionally and rank the remaining installs by mtime, so a requested count of zero, one, or two preserves the current install plus that many previous installs whatever the current install's own mtime rank. Both bound the count by what exists rather than demanding it: retention stops at kept_previous < keep_previous, so a request for two against a single eligible previous install keeps that one and reports success. Show protects one thing more: _install_dir_overlaps_protected() matches ancestors and descendants of a protected path, so a legacy install root that contains the current fingerprint directory survives a requested count of zero and is not one of the counted previous installs. Shared protection is exact-membership only, and its consumers' versioned layouts do not nest, so no overlapping install exists on this layer to protect. 343a6b4a50; hermetic probes 2026-08-24; test_show_runtime_clean_skips_legacy_parent_of_current_fingerprint
Step 4: Retention after pointer inspection failure Shared _current_install_dir() and Show _current_manifest_install_dir() both catch every pointer read/parse/path exception and return None, which contributes nothing to the protected set and leaves the live install ranked by mtime alone. With a corrupt, unreadable, or absent pointer both managers plan the live install for deletion at a requested count of zero, and at every requested count once the live install is no longer among the newest that count retains; each case still reports success. Show's archive pass in the same call refuses only for a present pointer it cannot read or parse, raising current.json is unreadable; an absent pointer is not a refusal there, because _protected_archive_sha256s() catches FileNotFoundError and keeps collecting protected digests from the retained installs' metadata. 343a6b4a50; hermetic probes 2026-08-24
Step 4: Downloads reclamation Shared cleanup enumerates staging directories and versioned installs only. At a requested count of zero, a real clean reclaims no bytes from downloads/ — a superseded archive, the current archive, an orphaned .tmp staging file, and a manifest cache all survive — and the result carries only ok and removed, reporting neither those artifacts nor any size. Show already reclaims content-addressed archives against a protected digest set and reports counts and bytes. 343a6b4a50; hermetic probe 2026-08-24
Step 4: Removal failure reporting Shared _clean_locked() deletes each staging directory and versioned install with shutil.rmtree(..., ignore_errors=True) and appends the path to removed unconditionally, then returns ok: True, so a removal blocked by permissions or an in-use file is reported as reclaimed. Show's archive pass instead unlinks each file under its own except OSError, increments failed_count, and adds to removed_bytes only after a successful unlink. In a real pass its outcome is three-way rather than binary: cleaned requires a zero failed_count, a nonzero failed_count with at least one successful unlink is partial, and a nonzero failed_count with no successful unlink is skipped; the latter two both carry skipped_reason: archive_removal_failed. The label alone does not identify a failure, because the dry-run branch reuses partial to mean only that reclaimable candidates exist, with failed_count: 0 and no skipped_reason. Within this archive report a failure is a present skipped_reason or a nonzero failed_count; that vocabulary is Show's own and is not the cross-runtime failure test, since shared clean() reports its failures as ok: False with a reason and neither of those fields. 343a6b4a50
Step 4: Archive protection for retained installs Show's _protected_archive_sha256s() protects three kinds of input, and its own docstring names only the first two: the current.json pointer, every remaining install's metadata, and — omitted there but present in the body — the configured archive_path when that file is content-addressed, which is how a direct-archive source persisting no install metadata keeps its own input. A retained install whose metadata is unreadable or malformed raises _ArchiveMetadataError rather than leaving that archive unprotected, and an uninspectable versions tree fails closed for the same reason. Shared cleanup reclaims no archives at all today, so it has no protected set to lose and none to inherit. 343a6b4a50; test_configured_prebuilt_archive_is_protected
Step 4: Cleanup safety wider than the protected set Show's cleanup suite proves archive safety through three mechanisms, only one of which is digest membership. test_archive_cleanup_never_touches_unknown_symlink_or_tmp_files survives by candidate filtering: a symlink, a directory, a .tmp file, a non-content-addressed name, and a trailing-newline name are never candidates, so no protected set is consulted for them. test_recent_unprotected_archive_survives_mtime_guard preserves a deliberately unprotected archive through a maturity window, because another process may have finalized it moments ago and not yet written install metadata. Neither outcome can be expressed as an input admitted to a digest set. fe0170c70; both named tests
Step 4: Post-install cleanup lineage coverage All three cases driving _clean_after_managed_install() were read: the first constructs the manager with no manifest_path, so every install carries the packaged lineage; the second retags all three installs to one custom manifest; the third uses two custom manifests, which both collapse into _CUSTOM_MANIFEST_LINEAGE and are ranked together. No case places a packaged and a custom lineage on one disk, so a successor that ranks installs by mtime across lineages passes all three while deleting the alternate lineage of a user who switches manifests. fe0170c70; the three test_clean_after_* cases at tests/test_show_runtime_archive_cleanup.py:160-239
Step 4: Archive cache is name-addressed ManagedRuntimeManager._resolve_manifest_archive() both reads and writes downloads/<archive.name>, so every install this layer has already performed cached its archive under the manifest's own filename rather than its digest. A successor adopting Show's content-addressed archive layout looks for a digest-named file, misses, and on an offline host reports archive_unavailable_offline with the correct bytes present on disk; preserving manifest-*.json does not help, because it is the archive that becomes undiscoverable. A case for this reads a cache directory produced by the pre-change code path, not one laid out by hand. fe0170c70
Inspection versus absence Shared versions-directory preview preserves traversal errors instead of treating them as proof of no install; Show status can still collapse a raised inspection into absent at its consumer boundary. 2c6fcbe88
Step 3: Released Show links Each v3.0.13 Darwin/Linux archive has 16 symlinks and one esbuild hard link; the four Unix archives have nine forward symlinks total, prior-target hard links, and no finally dangling symlink. Windows archives have no links. v3.0.13 manifests and archives; measured 2026-08-23
Step 3: Extractor behavior Shared stops at the first link member. Show and tmux accept the benign regular/symlink/hard-link probe and raise on an escaping linkname. 2c6fcbe88; hermetic probe 2026-08-23
Step 3: Filter capability The project supports Python 3.10+. Show capability-detects filter="data"; shared and tmux use a Python 3.12 version gate even though the filter is backported to 3.10.12 and 3.11.4. 2c6fcbe88; Python docs checked 2026-08-23

Step 1 Executable Acceptance

Intent: Move installed-state truth for git, Memory, and model-hub from the selected manifest to admitted disk records and artifacts. Status, resolvers, and reuse derive installed identity from disk while manifest failure remains a separate candidate-operation diagnostic; Show and tmux are unchanged.

Every Step 1 shared consumer rejects external or symlink-resolved pointer paths. Model-hub claim cases cover schemas 1 and 2 and normalize whole-manifest targets for resume/recovery; acceptance verifies each fixture's released version, digest, and source bytes. The entrypoint universe is generated from the public operation surface exported by the Step 1 manager and adapter code, with a reflection check that fails when that surface and its code-owned contract registry differ. The executable contract is the Cartesian coverage matrix for each fixture's owning adapter; adding a fixture or public operation creates an uncovered cell until its test exists. Each adapter has a non-empty fixture set, and every cell asserts its fixture's output and mutation predicates rather than counting a smoke call.

Two mechanical rules gate Step 1:

  1. Before implementation, record and rg-verify a non-empty baseline enumeration of every production or test symbol scheduled for deletion. Every listed symbol has zero definition and call-site hits at the deletion commit.
  2. At delivery, record and rg-verify a non-empty enumeration of every predicate whose text differs between the step's merge base and delivered head, keyed by owning symbol and call site. Every listed predicate maps to a retained executable predicate or an explicitly approved behavior change; an unaccounted row fails. Each retained predicate has a non-zero production call-site count and an acceptance test that exercises it.

A step gate is self-checked against its intent: an unchanged-result clause is valid only for behavior that the intent does not require changing. Enumeration binds when a gate becomes executable: the in-flight step's allowed and forbidden sets are author-verified with rg as enumerated symbols or census rows. Later gates state only direction and a stop condition; the PR that makes one executable inherits its enumeration obligation. Deferred intents name inherited obligations and required end-state properties; fixtures, operating-system jobs, and scenario lists remain implementation-time proof methods.

Migration Sequence And Gates

The following mechanical gates apply to every step:

  1. A non-dunder shared hook that this migration introduces, or converts from raise NotImplementedError to concrete behavior, fails when every on-layer consumer overrides it; at least one must inherit it unchanged.
  2. A new public shared-layer symbol with zero production call sites fails the step. Test-only call sites do not count.
  3. The contract author marks each normative row of the Measured Current-Behavior Census with its owning step. All and only the census rows marked for a step define that step's corpus membership, which implementation cannot elect. Every marked row has an executable case. A marked row whose own observation cites a released artifact or record additionally requires a fixture provenance-verified against the released version and digest it derives from. A row citing no released bytes — an interpreter capability, a code behavior, or a constructed hostile input — has no released fixture to verify and is covered by its executable case alone; the row text decides this and implementation never classifies rows. An unmarked census row states an observation, so it contains no MUST, rejects, or fails; that prohibition is the whole test, because a path-naming clause cannot distinguish a production path from a fixture path under rg. Both halves scope to that census table alone, so the other tables in this document keep describing current behavior in their own words.

Step 2: Converge The Mutation Guard

Intent: Move the strongest existing guard and preview behavior into the shared manager so later installer migrations inherit one concurrency owner.

Gate: Shared consumers pass focused guard, preview, cleanup, and install tests with no installed-runtime regression. Lost path confinement, retained misclassification, or a consumer result change outside the corrections measured in the Mutation lock follows/under-validates its path and Preview collapses failure causes rows stops the sequence before Show uses the guard.

Step 3: Support Composite Artifacts

Intent: Let the shared installer represent Show's released directory artifact and internal links under the Step 1 disk-state model and Step 2 mutation guard while retaining the binary-artifact path; reuse capability detection for tar filtering without raising the Python floor.

Gate: Every released v3.0.13 platform archive measured in the census installs through the shared path and exposes its expected CLI/esbuild entrypoints, hostile archive probes remain confined, and git/Memory/model-hub fixtures stay unchanged; failure breaks a supported platform or weakens existing binary consumers, so the sequence stops before cutover.

Deferred hardening (non-gating): both current extractors have an unfiltered fallback and no explicit final-tree ownership or POSIX-mode normalization.

Step 4: Add Shared Retention

Intent: Give the shared manager one lifecycle for verified downloads, installed versions, protected rollback state, and cleanup reporting under the Step 2 guard, exposed through vibe runtime clean for every on-layer consumer.

Deliverable: shared retention and archive reclamation for the on-layer consumers, exposed through vibe runtime clean, which gains Memory and model-hub cleanup beside the git pass and the Show pass it already runs.

Gate: Every marked Step 4 census row has an executable case, plus every case in tests/test_show_runtime_archive_cleanup.py that a shared successor takes over, passing unweakened. Both are artifacts that already exist — measured rows with citations, and 51 cases holding behavior the shared layer must not lose — and this contract deliberately does not restate what they assert. The terseness is the result, not an omission: this section's review history is a record of restatements drifting from the behavior they copied while the direction below drew no findings at all. The suite is necessary and not sufficient, and the three marked rows naming its own coverage gaps are in the census above.

What the step must not do is stated as outcomes, which is what this document can hold without drifting. Any on-layer consumer's loss stops rollout for that dependency. Where a bound stays imprecise, cleanup errs toward not deleting: an uncleaned directory costs disk space, while a deleted live install costs a redownload the user cannot undo. A cleanup reporting success while a removal did not happen, and a command exiting zero while a runtime it invoked failed, are both defects of this step whatever field carried the signal.

The one behavioral ruling this step makes is on the protected set, because the census row above records both managers treating an unreadable pointer as though nothing were current. A pointer that is present but does not resolve to a confined current install is an inspection failure: cleanup plans no deletion and reports that failure instead of reporting success. Only a genuinely absent pointer means nothing claims to be current. Protection of the live install follows from this ruling and never from its mtime rank, so a requested retention count of zero protects it as strongly as any other count. Which pointer shapes fail inspection is the implementation's to enumerate and test, not this contract's to list.

Deferred, not dropped: automatic post-install retention. This step delivers the command, so the shared ensure() gaining its own cleanup call is a separate decision and not a gate item here. That defers the work; it does not leave the behavior ownerless. Show runs _clean_after_managed_install() after every successful managed install today, and this contract does not enumerate what that method guarantees — its properties are held by tests/test_show_runtime_archive_cleanup.py, which is where the Step 6 successor must prove it inherited them. Step 6 deletes the method with the rest of Show's parallel installer, so the obligation to place automatic post-install cleanup on the shared layer transfers to the Step 6 gate rather than expiring here.

Sequencing within the step: the protected-set correction lands before any reclamation is added, because reclamation widens what an empty protected set can delete.

Show carries the same pointer-inspection defect today and is not patched separately for it: Step 6 deletes the Show cleanup that holds it, so a Show-side fix would be discarded at cutover, and the exposure until then is a redownload of a re-obtainable runtime behind a damaged pointer. Show's archive pass is the precedent the shared ruling adopts rather than a new policy.

Retention here is bounded by count, not by reference, and this step does not change that. show-runtime-availability.md records that a cached _managed_command can still name an install directory after the pointer advances, that the runtime require()s modules lazily for its whole lifetime, and that keep_previous therefore bounds retention by count rather than by reference; W6 owns closing it. Show's own cleanup carries the identical count bound today, so putting Show on this layer at Step 5 neither closes nor widens the exposure, and no gate above should be read as closing it. The one bound this step does owe is negative: the reclamation it adds targets archives under downloads/ and install-* staging directories, which no handed-out command names, so it must not extend the exposure from install directories to newly reclaimed bytes.

Step 5: Cut Over Show's Manifest Provider

Intent: Compose Show's manifest provider as a full consumer of Steps 1-4 while leaving direct archive, npm, Node policy, availability, and serving behavior in Show; align unreadable-source diagnostics and admission-relevant manifest changes during that measured cutover.

Gate: Released and canonical Show fixtures cover online, offline, provider, layout, Node, Doctor, dependency-status, and composite-archive flows with one declarative manifest installer owner; any released install that disappears, redownloads, or cannot serve on its previously supported platform stops deletion.

Step 6: Delete Show's Parallel Installer

Intent: Remove unreachable Show manifest installation, cache, guard, cleanup, persistence, and utility ownership while retaining product adapters.

Gate: Deleted Show symbols have zero definitions and call-site hits in source and tests, focused suites for the four migrated consumers pass, and no private compatibility shim recreates a second installer; tmux remains the one temporary outlier. Automatic post-install cleanup exists on the shared layer, inherited from Step 4, before _clean_after_managed_install() is deleted. Its acceptance is not a written property list — the first draft of this sentence named one property, never-fail-the-install, and thereby licensed a successor that would drop the manifest-lineage scoping the method also carries, letting a user who alternates between the packaged and a custom manifest lose the other lineage's installs. It is instead the existing suite: every case in tests/test_show_runtime_archive_cleanup.py that drives _clean_after_managed_install() passes against the shared successor, retargeted but not weakened, before the method is deleted.

That binding covers the behavior and not its invocation, and today nothing covers the invocation: all three of those cases call the method directly, the tests that drive _install_managed_runtime_locked() assert nothing about cleanup, and no test anywhere proves that completing an install runs cleanup at all. Retargeting the three onto a shared helper would therefore pass while the post-success call site disappeared, and installs and archives would accumulate with nothing failing. So this step also owes one test that a completed install invokes the shared successor — either by driving a production install entrypoint and observing the cleanup, or by asserting the call edge in the manner test_provider_install_entrypoints_converge_on_single_admission_owner already uses for _install_managed_runtime_locked. Deleting the last caller of a behavior is the same defect as deleting the behavior, and neither a symbol count nor a retargeted unit test can see it.

Step 7: Migrate Tmux And Enforce Sole Ownership

Intent: Move tmux onto the proven shared installer after Show as a full consumer of Steps 1-4, retaining its released-state reader, macOS preparation, and runtime compatibility adapter.

Gate: Released tmux inputs and prepared-binary tests pass through the shared path and the other four dependencies remain unchanged. The non-empty obsolete adapter-owned installer-symbol sets recorded at the Step 6 and Step 7 baselines have zero definitions and call-site hits. vibe runtime clean reaches tmux: the CLI branch invokes each manager by name rather than discovering on-layer consumers, so joining the layer does not wire the command up, and without this tmux versions and downloads accumulate with no way to reclaim them. Adding tmux to the command satisfies this; making the command enumerate on-layer consumers instead satisfies it and stops the next joiner from needing the same edit. The end state has one declarative manifest installer owner for all five dependencies.

Measured Size And Concept Estimate

All rows below are non-normative planning measurements. Function spans use end_lineno - lineno + 1; imports, declarations, blank lines outside functions, serving-only functions, and tests are excluded.

Measurement Value Measured at
Show file / tmux file / combined outliers 3,370 / 699 / 4,069 physical lines 2c6fcbe88
Show install roots before GitHub-provider removal 110 functions / 2,579 span lines 903414cc4; revalidated 2c6fcbe88
GitHub-only reachable helpers 11 functions / 212 span lines 903414cc4
Show install roots after that prerequisite 99 functions / 2,367 span lines derived from the same audit
The 24 same-name pairs 561 Show span lines 2c6fcbe88
Supplied uncounterparted grouping 1,621 Show lines supplied audit at 903414cc4
Tmux functions 38 functions / 568 span lines 2c6fcbe88

The historical implementation estimate, measured before later seams were discovered, is retained only to answer the sizing question; it is not maintained as future steps are designed.

Historical estimate Show / Steps 1-6 Tmux / Step 7 Total Measured at
Lines deleted from outlier modules 1,560-1,650 489-539 2,049-2,189 2c6fcbe88 planning model
Existing behavior moved by ownership 732 451 1,183 2c6fcbe88 planning model
Lines added to shared layer 510-610 20-50 530-660 2c6fcbe88 planning model
Net production reduction 950-1,140 439-519 1,389-1,659 2c6fcbe88 planning model

The original owner-instance model counted seven common capabilities (primitives/extraction, manifest selection, archive acquisition/cache, install transaction/persistence, mutation/preview guard, retention/cleanup, and status/probe), four Show product concepts, and two tmux product concepts. Its historical forecast was 26 concepts before and 13 after, measured at 2c6fcbe88. Later discovery of Memory's development-provider and coordinated activation seams makes that arrow non-exhaustive; it is not recalculated or used as acceptance evidence. The retained product inventory includes those two Memory seams alongside the four Show and two tmux concerns named above.

A surviving duplicate owner is a defect; missing a forecast range is not.

Residual Unknown

Detailed contracts for Steps 2-7 are deliberately deferred, not silently assumed. Each is written from the measured output of its predecessor. The prior Python-floor question is resolved: keep requires-python >=3.10 and prefer the existing capability-detection pattern. Step 3 gates path/link confinement; final-tree mode/ownership alignment remains deferred hardening. There is no remaining archive-link or Python-release decision in this document.

Non-Goals

  • No production code or test change in this PR.
  • No change to Show serving or request behavior.
  • No resurrection of the removed GitHub provider.
  • No attempt to force direct archive or npm into the manifest security model.
  • No deletion of released compatibility readers by this document.
  • No issue filing and no dependency addition.