[apotema]

Problem

Every labelle process on a machine shares one LABELLE_HOME, and a CI shell runner (Flying Platform's fp-ubuntu now runs 3 jobs at once) shares it across concurrent jobs. The assembler download staged on a fixed <dest>.part. In FP pipeline #57, test-game and test-game-android both fetched assembler v0.126.0 into the same .part. One renamed it into place, and the other failed:

labelle: could not read the download to verify it.
labelle: assembler version 0.126.0 not found in cache.
error: AssemblerNotCached

astcenc (zip + unzip in place in the version dir) and managed Python (shared archive path, deleteTree then extract in place) had the same race, and theirs was worse.

Fix: src/cli/cache_publish.zig

• tempSibling(dest, tag) returns <dest>.tmp-<pid>-<16 hex>. It sits in the same directory, so the final rename is atomic, and the name is unique across processes and threads.
• InstallLock is an exclusive, blocking advisory lock on <dest>.lock that the OS releases if the holder dies. Only one process downloads; the others wait, re-check, and reuse the result.
• publishFile(staged, dest, validator) publishes with one rename. If dest already validates (before we start, or after a failed rename, e.g. Windows refusing to replace a running exe), ours is discarded and theirs is used. staged never survives the call.
• publishDir(staged, dest, validator) does the same for a tree. A broken leftover at dest is moved aside in one rename, ours goes in, and the old tree is deleted, so the two are never mixed.

Applied to every download into the cache:

Path	Before	After
assembler (downloadAssembler)	fixed .part, fixed .sha256sums, chmod after publish	lock + unique staging (manifest path follows), verify the staged file, chmod before publish, keep a concurrent winner whose bytes match the SHA256SUMS digest, curl timeouts
astcenc (astcenc_bin.ensure)	curl + unzip into <ver>/ in place	lock, download + extract into a unique staging dir, publish the tree with one rename, archive not kept
managed Python	shared python-download.tar.gz, deleteTree(py_dir) + extract in place	lock, unique archive + staging dir, validate the staged interpreter, publishDir
provider archives (cache read + providers fetch)	unique temp + rename	publishFile with the pinned sha256 (keeps a concurrent winner, handles Windows rename-over failures)
managed Zig	lock + staging, PRNG name	staging name from tempSibling
labelle update	fixed $TEMP/labelle-update, mv across filesystems	unique sibling of the installed binary (same-FS rename), temp removed on failure

Also: when SystemRoot is unset, astcenc's Windows extract now tries the stock C:\Windows\System32\tar.exe before bare tar.

Tests

• cache_publish: tempSibling shape and uniqueness; publishFile (publish / keep valid / replace damaged); publishDir (publish / keep valid / replace partial leftover); 8-thread races for unlocked publishFile and locked publishDir, asserting all succeed, the result verifies, and no staging leftovers remain.
• assembler.ConcurrentDownload: 6 parallel downloadAssembler calls into one cache against a file:// release fixture (6 MiB asset + SHA256SUMS) through real curl. All succeed, the binary verifies, and only the binary and its .lock are left in the slot. A tampered asset leaves nothing at the final path.
• astcenc: 6 parallel ensure calls into one labelle home against a file:// zip fixture. Every binary is complete, and nothing besides the version dir and its lock is left.

zig build test -j2 on Windows: 1070 pass, 100 skip, 4 fail. Those 4 are the same as on main on this machine: pack symlink tests that need the symlink privilege.

https://claude.ai/code/session_01Hpt1haxcboZPznpG1KqDRS

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Team
• Run ID: 04b386ef-0696-481f-a195-be4443793771

Commits

Reviewing files that changed from the base of the PR and between 56f0d2c and df35f28.

Files selected for processing: 9

• src/astc/astcenc_bin.zig
• src/cli.zig
• src/cli/assembler.zig
• src/cli/cache_publish.zig
• src/cli/provider_github/archive.zig
• src/cli/provider_github/fetch.zig
• src/cli/python_provision.zig
• src/cli/update.zig
• src/cli/zig_toolchain.zig

Included review availability: This review used your included allowance. 9 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 10 reviews per hour.

Walkthrough

The CLI adds shared cache-publication helpers and applies staged downloads, validation, and install locks to several tool and archive installation flows. Tests cover publication outcomes and concurrent installs.

Changes: Cache installation and publication

Layer / File(s)	Summary
Staging and publication helpers src/cli/cache_publish.zig, src/cli.zig	Adds unique sibling paths, per-destination locks, file and directory validators, and publication helpers. Tests cover cleanup, replacement, and concurrent publishers. The CLI test root imports the related modules.
Verified file downloads src/cli/assembler.zig, src/cli/provider_github/*	Assembler downloads use manifest digests, locking, and staged publication. GitHub archive downloads publish with pinned hashes and size limits. Tests cover parallel downloads and checksum rejection.
Staged directory installations src/astc/astcenc_bin.zig, src/cli/python_provision.zig	ASTC and Python installs validate staged directories before publication. Both flows serialize installation with locks. ASTC also adds a Windows tar.exe fallback and concurrent-install tests.
Update and toolchain staging src/cli/update.zig, src/cli/zig_toolchain.zig	CLI updates use unique sibling download paths and attempt cleanup on download failures. Zig toolchain staging uses the shared unique-sibling helper.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Ensure as astcenc.ensure
  participant Lock as InstallLock
  participant Release as Release server
  participant Stage as Staging directory
  participant Publish as cache_publish.publishDir
  participant Cache as Cache directory
  Ensure->>Lock: acquire destination lock
  Lock-->>Ensure: return acquired lock
  Ensure->>Cache: recheck for candidate binary
  Ensure->>Release: download archive to staging
  Ensure->>Stage: extract and validate candidate
  Ensure->>Publish: publish completed staged directory
  Publish->>Cache: rename staged directory into cache

Loading

Possibly related issues

• labelle-toolkit/labelle-cli issue 528: This change makes shared cache downloads and publication safe for concurrent Labelle processes. It does not cover the issue’s Docker, compiler, linking, or benchmark work.

Merge Risk: Minimal · up to df35f

No actionable issue was established in the reviewed cache-installation changes; the PR is ready for normal merge checks.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title "fix(cache): concurrency-safe downloads into the shared labelle home" matches the main change. The changeset adds unique staging paths, per-destination install locks, and atomic publication …
Description check		The description explains the problem (concurrent labelle processes sharing LABELLE_HOME and a fixed .part staging path causing a race), the fix (cache_publish.zig helpers, InstallLock, publishFile, pu…
Docstring Coverage		No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title "fix(cache): concurrency-safe downloads into the shared labelle home" matches the main change. The changeset adds unique staging paths, per-destination install locks, and atomic publication (cache_publish.zig) and applies them to assembler, astcenc, managed Python, provider archives, managed Zig, and labelle update downloads. The title is specific, short, and states the primary intent.

Full details: Description check

Explanation

The description explains the problem (concurrent labelle processes sharing LABELLE_HOME and a fixed .part staging path causing a race), the fix (cache_publish.zig helpers, InstallLock, publishFile, publishDir), a per-path before/after table, the Windows System32 tar.exe fallback, and the tests added. Each of these matches files in the changeset.

Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 0 files. (9 skipped: 9 unsupported.)

Finishing Touches

Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-31T05:44:33.715322Z	df35f28	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.