[Bug] Local bundle install can advance records without updating existing components

[joey-orbyss]

Spec Kit version

Reproduced with specify 1.0.4 on Windows.

Reproduction

1. Install a bundle version whose workflow, two extensions, and preset are already present in an initialized project.
2. Point a clean local release directory at a newer version of the same bundle and components.
3. Run:

specify bundle install C:\path\to\new-release\bundle.yml --offline --integration codex

The command reports success, for example:

Installed 'program-kit' (0 added, 4 already present).

It advances .specify/bundle-records.json and its contributed-component versions to the new bundle version, but the installed workflow/registry, extension manifests, and preset/registry can remain at the old version. A subsequent component tool can therefore appear current while executing old code.

When components were installed individually before the bundle, the successful local bundle install can instead create a record without the expected contributed-component entries because every primitive is classified as already present.

Expected behavior

Bundle installation/update should be transactional across its record and primitive installations:

• update every component to the resolved version before advancing the bundle record;
• validate installed manifests and registries against the resolved bundle before returning success;
• retain the previous coherent record or fail if a primitive update fails; and
• serialize writes when multiple extensions share registry/configuration files.

At minimum, an existing component with a different version must not be treated as satisfied solely because its ID is present.

Impact

The project records a coherent new bundle version while continuing to execute old extension code. In the observed consumer, managed synchronization misleadingly reported all files unchanged until each workflow, extension, and preset was explicitly reinstalled in sequence.

[github-actions]

Bug assessment — local-bundle-stale-components: Valid · severity medium

---

Bug Assessment: Local bundle install can advance records without updating existing components

• Slug: local-bundle-stale-components
• Created: 2026-09-04T13:33:25.283Z
• Source: issue [Bug] Local bundle install can advance records without updating existing components #4434
• Verdict: valid
• Severity: medium

Report (summarized)

The reporter reproduced this with specify 1.0.4 on Windows. After a bundle and its workflow, two extensions, and preset were already installed, installing a newer local release with specify bundle install <local bundle.yml> --offline --integration codex reported success such as Installed 'program-kit' (0 added, 4 already present). The bundle record and component versions in .specify/bundle-records.json advanced, while installed workflow/extension/preset files, manifests, or registries could remain at the previous version. The report also describes a second case where components installed individually before the bundle caused the new bundle record to contain no expected contributed-component entries because every primitive was classified as already present.

No additional comments supplied reproduction details or context.

Symptom

A bundle install can treat an installed component as satisfied by ID alone, so a newer bundle version is recorded even though the on-disk primitive remains old. This can make later tooling report the component as current while it executes stale workflow or extension code; independently installed components can also remain unowned by the bundle record.

Reproduction

1. Initialize a project and install an older bundle version containing a workflow, two extensions, and a preset.
2. Prepare a newer local release of the same bundle and component set.
3. From the project, run specify bundle install C:\path\to\new-release\bundle.yml --offline --integration codex.
4. Observe a success message reporting all components as already present, then compare .specify/bundle-records.json and the installed primitive manifests/registries with the resolved bundle version.

A related reported path is:

1. Install the components individually before installing the bundle.
2. Run the local bundle install.
3. Inspect the resulting bundle record for missing contributed-component entries.

[NEEDS CLARIFICATION: the report does not include the exact bundle manifests, component versions, or the before/after contents of the affected registries and manifests.]

Suspected Code Paths

• src/specify_cli/commands/bundle/__init__.py:347-439 — bundle_install resolves the local manifest and invokes install_bundle(...) without refresh=True; success output only distinguishes installed from skipped.
• src/specify_cli/commands/bundle/__init__.py:442-492 — bundle_update does pass refresh=True, showing that explicit update has a separate refresh path and is the current workaround for owned components.
• src/specify_cli/bundler/services/installer.py:59-87 — install_bundle documents and implements ID-based installed checks for normal install; version pins are not compared when an installed component is skipped.
• src/specify_cli/bundler/services/installer.py:97-131 — is_installed(...) is checked before installation. Existing components are skipped unless they are owned and the caller requested refresh; independently installed components are intentionally not attributed or refreshed.
• src/specify_cli/bundler/services/installer.py:168-176 — the new plan.version and the collected component references are saved after the loop, even when existing components were skipped, allowing the bundle record to move ahead of on-disk state.
• src/specify_cli/bundler/services/primitives.py:228-300 and :315-369 — extension and workflow managers expose ID-based is_installed checks, while version-aware reapplication is available only through their install/refresh paths.
• tests/integration/test_bundler_install_flow.py:40-51 — existing tests lock in idempotent normal install behavior: a second install skips all four components.
• tests/integration/test_bundler_install_flow.py:387-425 — existing tests explicitly preserve the no-collateral rule by skipping and not attributing components installed independently of a bundle.

Root Cause Hypothesis

Confidence: high. The normal bundle install path conflates “the component ID exists” with “the component satisfies the manifest’s pinned version.” install_bundle only invokes primitive installation when is_installed is false, and it only refreshes already-present components when refresh=True; the CLI supplies that flag only for bundle update. It then persists the resolved bundle version after the loop. The independently-installed case is a related ownership-policy consequence: the current implementation deliberately does not claim pre-existing untracked components to avoid removing user-owned components later, so a successful bundle install can legitimately produce an empty or partial contributed_components list under that policy.

Proposed Remediation

Preferred: Make bundle installation version-aware and transactional. When a bundle ID already has a record, treat installing a newer resolved version as an update (or reject it with an explicit instruction to use bundle update) and route owned components through the primitive refresh/reinstall path before writing the new record. For all already-present components, obtain or validate their installed version/manifest rather than accepting presence by ID. If an unowned component is present at a different version, fail before advancing the bundle record unless the user explicitly opts into adoption; if it is already at the required version, preserve the no-collateral ownership rule.

Persist the record only after every planned component has been installed, refreshed, or verified to satisfy its pin, and retain the previous record on failure. Because refresh operations can modify shared registries/configuration files, use the existing managers’ atomic/serialized write facilities or add a bundler-level transaction/rollback contract that covers refreshed components as well as newly installed ones. Keep contributed_components as provenance unless an explicit adoption model is designed; if records must list every resolved component, add separate desired/owned state instead of silently changing removal semantics.

Alternatives:

• Make bundle install refuse an already-recorded bundle and require bundle update. This is lower risk for CLI semantics but does not solve the independently-installed, mismatched-component case without version validation.
• Add a --adopt or equivalent explicit mode for independently installed components. This can satisfy bundle ownership and future removal, but requires clear user consent, version checks, and tests preventing accidental collateral removal.

Files likely to change:

• src/specify_cli/commands/bundle/__init__.py
• src/specify_cli/bundler/services/installer.py
• src/specify_cli/bundler/services/primitives.py and/or the primitive managers that expose installed metadata
• src/specify_cli/bundler/models/records.py if desired-versus-owned state is introduced
• tests/integration/test_bundler_install_flow.py
• Additional primitive/CLI contract tests covering local offline installation and refresh failure

Tests to add or update:

• Install bundle v1, install the same bundle ID at v2 through the local bundle install path, and assert each owned primitive is refreshed before the record changes.
• Assert a refresh or primitive failure leaves the prior bundle record and a coherent primitive state, including a failure after one or more shared registry writes.
• Assert a pre-existing unowned component at a mismatched version fails closed and does not advance the record.
• Assert an unowned component at the requested version follows the documented ownership policy and cannot be removed accidentally by bundle remove.
• Assert the CLI success summary distinguishes added, refreshed, skipped, and failed outcomes accurately.

Risks & Considerations

• Automatically refreshing or adopting independently installed components could violate the existing FR-022 no-collateral removal guarantee; explicit ownership/adoption semantics may be safer.
• Primitive managers currently use different metadata and update mechanisms, so a common version-inspection interface may require API changes and per-kind handling.
• Full rollback of refreshed components and shared registry/configuration files may require atomic file writes or backups and careful cleanup on Windows.
• Changing repeated bundle install from idempotent skip behavior to update behavior could alter scripts that rely on the current semantics; an explicit refusal or opt-in flag is a lower-compatibility-risk alternative.

Open Questions

• [NEEDS CLARIFICATION: Should bundle install on an already-installed bundle be an update operation, or should it fail and require bundle update?]
• [NEEDS CLARIFICATION: Should a bundle claim components that were installed independently, or should contributed_components continue to mean only components installed/adopted by that bundle?]
• [NEEDS CLARIFICATION: Which workflow, extension, preset, and registry versions were present before and after the reported specify 1.0.4 run?]

Generated by 🐛 Assess Bug from Labeled Issue for issue #4434 · 87.9 AIC · ⌖ 14.9 AIC · ⊞ 28.3K · ◷