SDK closure: decide separate offline installer pin vs runtime upgrade for expired-cache rollback preparation

[Yeachan-Heo]

Migrated from #6024 (originally opened by @nahyeongjin1).

Decision requested (test-build policy, not an implementation PR)

May the SDK rollback proof use a separately pinned Bun 1.4.1 dependency installer while keeping the host, native-build/embed and compiler on 1.4.0, or would maintainers prefer a separately qualified repository-wide upgrade?

Installer-only separation is the narrowest unproven design candidate, not an approved fix. It changes the existing single-toolchain preparation policy. No implementation or end-to-end host-1.4.0 success is claimed. No new public SDK runtime selector is requested.

Current contract and why a fixture-only bump is insufficient

Observed at PR #6019 head be2dfda171bb4a6bc8f9c644dca905fb669ea1f1. I also read current dev 8cd17c0f636d3c541c0c2af184e01709b0e6f2c1: root remains bun@1.4.0, and the rollback test and manifest are byte-identical to the PR head.

• Root host pin and fixture toolchain/commands.
• Host equality assertion: manifest.toolchain.version === Bun.version.
• Inherited environment/PATH, followed by install/native/embed/compile stages. Bare bun currently selects all stages; changing a JSON version does not select a separate executable.
• Pinned historical source and artifact contract: unchanged base aedd0df99e7c9dff420b50f7ff47bd6645627bdd, fresh isolated worktree, frozen install, newly compiled/host-signed executable, hash immediately before invocation. It is not a fixed prebuilt-binary contract.

Changing only the fixture version to 1.4.1 was rejected by a real focused run on host 1.4.0: 0 pass / 1 fail / 2 filtered, line 229 (Expected: 1.4.0, Received: 1.4.1). Deleting that assertion would weaken the proof, not establish installer/compiler isolation.

Observations versus diagnosis

On macOS arm64, unchanged catalog-linked historical preparation fails under network denial with naturally expired cache: 1.4.0 attempts registry metadata lookup despite the existing --offline --frozen-lockfile argv.

A prior bounded investigation executed 16 install invocations (not 16 closure runs):

Case	Installed + official 1.4.0	Official 1.4.1
Original synthetic linked-catalog graph / expired complete cache	both exit 1, DNS failure	exit 0
install.prefer = "offline", install.offline = true, or --prefer-offline	all exit 1	not used as a workaround
Same directory preinstalled by 1.4.1, then rerun canonical 1.4.0 install	both exit 1	both preparation runs exit 0
Empty-cache negative control	—	exit 1, explicit offline cache miss
Synthetic local-child edge changed to workspace:*, matching lock literal	both exit 0	—

Breakdown: 10 unchanged-graph 1.4.0 failures, 3 successful 1.4.1 installations, 1 negative 1.4.1 cache-miss control, 2 modified-graph 1.4.0 successes. Config/flag options and prepared node_modules did not solve this condition. These are reviewed execution receipts; I did not rerun the entire matrix for publication.

This is not a claim that every cache-only 1.4.0 install fails. The direct-workspace positive control succeeds. The graph reload plus metadata freshness explanation is supported by the controls and upstream changes; this does not isolate which upstream change alone suffices for the full historical graph.

Official primary sources, checked at version tags rather than substituting current docs:

• Bun 1.4.0 installer options lack installer offline-mode wiring; 1.4.1 options contain it. Official binaries also differ in install --help.
• Offline install introduction, #40010 explicitly distinguishes the older runtime auto-install bunfig setting from the newly supported installer behavior.
• Workspace reload/parser alignment, #41302 addresses catalog/workspace parsed-shape consistency. Both commits are ancestors of the official 1.4.1 tag, checked through the GitHub compare API.

The previously recorded 2651 pass / 0 fail whole closure used the task-local 1.4.1 candidate. It is not a host-1.4.0 closure pass and does not validate installer-only separation. No Linux/Windows execution is claimed.

Public minimal reproduction

Below is the actual sanitized script rerun for this publication, independent of private paths or source trees. Requires macOS sandbox-exec, Python 3, official Bun 1.4.0/1.4.1 executables, and an existing complete cache containing the public regexp-tree@0.1.27 package and registry manifest whose freshness has naturally expired. A fresh cache may not reproduce the failure; an incomplete cache tests a different condition. Do not edit cache TTL/clock or rewrite cache bytes to manufacture expiry. The script does not warm/download dependencies. Use a disposable cache copy if you want to preserve your original cache.

Save the following as offline_repro.py, set BUN140, BUN141, CACHE, and SCRATCH to your own executable/cache/disposable-directory paths, then run:

"$BUN140" --revision
"$BUN141" --revision
python3 offline_repro.py --bun "$BUN140" --cache "$CACHE" --scratch "$SCRATCH"
python3 offline_repro.py --bun "$BUN141" --cache "$CACHE" --scratch "$SCRATCH"
python3 offline_repro.py --bun "$BUN140" --cache "$CACHE" --scratch "$SCRATCH" --direct-workspace

Fresh publication execution: official 1.4.0+34cbb9a40 => install exit 1/DNS failure; official 1.4.1+4661e494f => install exit 0/package present; 1.4.0 direct-workspace control => install exit 0/package present. All three retained source/lock bytes during installation. The Python harness exits normally and reports the install's exit in JSON. These are three additional minimal installations, not a full closure rerun.

Executable minimal fixture and network-denied runner

import argparse, hashlib, json, os, pathlib, subprocess, tempfile
p = argparse.ArgumentParser()
p.add_argument('--bun', required=True)
p.add_argument('--cache', required=True, help='existing complete, naturally expired cache')
p.add_argument('--scratch', required=True, help='existing disposable parent directory')
p.add_argument('--direct-workspace', action='store_true')
a = p.parse_args()
bun = str(pathlib.Path(a.bun).resolve())
cache = str(pathlib.Path(a.cache).resolve())
FILES = {'package.json': '{"name": "offline-catalog-repro", "private": true, "workspaces": {"packages": ["packages/*"], "catalog": {"child": "1.0.0", "regexp-tree": "^0.1.27"}}}', 'bunfig.toml': '[install]\nminimumReleaseAge = 259200\nlinker = "hoisted"\n', 'bun.lock': '{\n  "lockfileVersion": 2,\n  "configVersion": 1,\n  "workspaces": {\n    "": {\n      "name": "offline-catalog-repro",\n    },\n    "packages/app": {\n      "name": "app",\n      "version": "1.0.0",\n      "dependencies": {\n        "child": "catalog:",\n        "regexp-tree": "catalog:",\n      },\n    },\n    "packages/child": {\n      "name": "child",\n      "version": "1.0.0",\n    },\n  },\n  "catalog": {\n    "child": "1.0.0",\n    "regexp-tree": "^0.1.27",\n  },\n  "packages": {\n    "app": ["app@workspace:packages/app"],\n\n    "child": ["child@workspace:packages/child"],\n\n    "regexp-tree": ["regexp-tree@0.1.27", "", { "bin": { "regexp-tree": "bin/regexp-tree" } }, "sha512-iETxpjK6YoRWJG5o6hXLwvjYAoW+FEZn9os0PD/b6AP6xQwsa/Y7lCVgIixBbUPMfhu+i2LtdeAqVTgGlQarfA=="],\n  }\n}\n', 'packages/app/package.json': '{"name": "app", "version": "1.0.0", "dependencies": {"child": "catalog:", "regexp-tree": "catalog:"}}', 'packages/child/package.json': '{"name": "child", "version": "1.0.0"}'}
if a.direct_workspace:
    FILES['packages/app/package.json'] = FILES['packages/app/package.json'].replace('"child": "catalog:"', '"child": "workspace:*"')
    FILES['bun.lock'] = FILES['bun.lock'].replace('"child": "catalog:"', '"child": "workspace:*"')
with tempfile.TemporaryDirectory(prefix='offline-repro-', dir=a.scratch) as tmp:
    work = pathlib.Path(tmp)
    for name, content in FILES.items():
        target = work / name
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(content)
    home = work / 'home'
    home.mkdir()
    env = {'PATH': str(pathlib.Path(bun).parent) + ':/usr/bin:/bin',
           'HOME': str(home), 'TMPDIR': str(work),
           'BUN_INSTALL_CACHE_DIR': cache}
    def hashes():
        return {name: hashlib.sha256((work/name).read_bytes()).hexdigest() for name in FILES}
    before = hashes()
    cmd = ['/usr/bin/sandbox-exec', '-p', '(version 1)(allow default)(deny network*)',
           bun, 'install', '--offline', '--frozen-lockfile']
    r = subprocess.run(cmd, cwd=work, env=env, capture_output=True, text=True, timeout=30)
    log = r.stdout + r.stderr
    print(json.dumps({'exit': r.returncode, 'sourceLockUnchanged': before == hashes(),
                      'dnsFailure': 'DNSResolveFailed' in log,
                      'offlineCacheMiss': '--offline:' in log,
                      'installed': (work/'node_modules/regexp-tree/package.json').exists()}))

Normal repository rollback entry point (requires the repository's provisioned native/build toolchains and pinned source object):

git checkout --detach be2dfda171bb4a6bc8f9c644dca905fb669ea1f1
bun --version # must be 1.4.0
bun test packages/coding-agent/test/sdk-downgrade-rollback.test.ts

Use a disposable checkout and the same expired-cache/network-denied condition when comparing the historical install stage. A normal online run is not evidence for the offline case.

Scope needed if separation is accepted

1. Distinct installer identity/version/provenance and portable trusted provisioning for macOS/Linux/Windows; fail closed on missing/wrong installer, with no implicit network fallback during the proof.
2. Preserve the exact host/compiler guarantee, route native/embed/compile and children to 1.4.0, and test PATH leakage. Do not silently select any first bun in PATH.
3. Preserve historical source/lock bytes, release-age policy, fresh isolated dependency tree, frozen/offline flags, and freshly compiled/signed executable hash checks.
4. Demonstrate RED for expired-cache preparation and wrong/missing tools; GREEN for the actual host-1.4.0 rollback and unchanged canonical closure, with relevant platform verification.

The synthetic catalog: → workspace:* control is not a proposed historical-source normalization: doing that to the pinned source/lock changes what the rollback proof rebuilds. Skipping reinstall, using archived node_modules or a prebuilt binary similarly changes the proof. Whole historical runtime 1.4.1 also changes the compiled old binary's embedded runtime; it is not equivalent to installer-only separation.

Duplicate/history comparison

Searched open issues/PRs and historical discussions for offline, toolchain, SDK downgrade, installer, 1.4.1, frozen lock, and catalog/cache. No existing discussion found that owns this expired-cache installer/runtime-split decision.

• fix(test): align rollback manifest with Bun 1.4 #4812 is the earlier 1.3.14 → 1.4.0 fixture alignment, closed as superseded by fix(runtime): complete the Bun 1.4.0 migration #4808. Its recorded 1.4.0 rollback success does not prove durable expired-cache behavior. fix(runtime): complete the Bun 1.4.0 migration #4808 itself was later closed without merge on its review boundary; I am not treating that closure as approval for a new toolchain policy.
• chore(deps): bump bun runtime pin to 1.4.0 #4795 is the earlier broad 1.4.0 migration; fix(ci): restore SDK closure checks #4614 concerns closure guard cwd/baseline restoration, not this installer behavior.
• SDK downgrade-rollback pretrain binary excludes win32 (supportedPlatforms: darwin/linux only) #2538 concerns Windows rollback platform support; current manifest already lists win32. This issue does not reopen that completed scope.
• SDK lifecycle/reconciliation issues SDK: turn.prompt acknowledgement is preflight-only; add durable acceptance and reconciliation #2930, SDK: retain turn.prompt_status across GJC session-process death/restart #3032 and sdk: session host self-reap strands a bound session and surfaces as an uncaught endpoint_stale #5633 concern separate contracts; no lifecycle unknown outcome is attributed to this installer failure or appended to them.

Please choose test-only installer separation versus a separately qualified repository-wide upgrade (or identify an existing supported policy that avoids both). This is a decision request, not a promise to implement either option. #6019 stays Draft/high-risk/needs-human; canonical validation and human review remain open.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]