[hhff]

devteam.mjs box-pins: verify, check and bump the box image's tool pins in cloud/Dockerfile, and check what the image installed. Feature box-latest-hub, story BOXHUB-S3; ticket kit-48-box-pins-command (risk high).

What it does

• box-pins verify [--release vX.Y.Z] (offline, in the kit's own checkout): every tool has its _VERSION ARG (a plain version) and, for gh, ttyd, mise and uv, both _SHA256 ARGs as 64 lowercase hex; no version or sum is written anywhere else in the file; DEVTEAM_RELEASE is vX.Y.Z and equals --release; DEVTEAM_BOX_TOOLS names exactly the six pins; every hold is exactly # hold: <reason> directly above a _VERSION ARG. Exit 0, or 1 naming each problem; 2 when there is no cloud/Dockerfile.
• box-pins check [--json]: each unheld tool against npm, PyPI or GitHub's releases (drafts and prereleases skipped, highest version taken): current, stale <pinned> -> <latest>, held <reason>, unknown <why>. Exit 1 if any is stale, else 3 if any upstream couldn't be asked, else 0; 2 for a file that doesn't verify.
• box-pins bump --release vX.Y.Z [--dry-run]: every unheld tool to its latest, each sum the sha256 of the downloaded asset (cross-checked against GitHub's published digest), DEVTEAM_RELEASE stamped. All or nothing: any upstream failure, or a result that would not verify, writes nothing. Writes atomically beside the file, keeping its mode; refuses a release older than the stamp.
• box-pins installed (inside the image, from any folder): runs each tool by its path in the image (/usr/local/bin, never PATH, where mise's uv comes first on the box) and claude-swap through UV_TOOL_DIR=/opt/uv/tools uv tool list, and compares with DEVTEAM_BOX_TOOLS. Exit 1 naming any mismatch; 2 outside the image.
• box-pins joins KIT_VIEWS (its comment now says bump writes cloud/Dockerfile); installed is machine-wide. Help says only the top package of the npm and PyPI tools is pinned.

Only docs/devteam/scripts/devteam.mjs and test/machine.test.mjs change; no file is added outside this ticket's records (docs/devteam-dev/tickets/kit-48-box-pins-command/).

How to verify

• node --test test/machine.test.mjs: the new tests use one in-process server for npm, PyPI and GitHub (DEVTEAM_PINS_*), a copy of cloud/Dockerfile with its pins fixed (so a real bump or hold never changes them), fake binaries under DEVTEAM_BOX_BIN, and no network. Every new test passes an env with DEVTEAM_IMAGE_HUB, DEVTEAM_KIT_RELEASE, DEVTEAM_BOX_TOOLS, GH_TOKEN and GITHUB_TOKEN cleared.
• node docs/devteam/scripts/devteam.mjs box-pins verify in this checkout: ok, 6 tools, release v0.52.0.
• node docs/devteam/scripts/devteam.mjs box-pins check (network): which pins are behind today.

What this doesn't defend against

• bump pins whatever upstream publishes: trust on first download, cross-checked only against GitHub's own digest. A compromised upstream release would be pinned. The reviewed release-prep PR (and its box-image build) is the check (m-20261115-012104539-supervisor).
• Only the top package of claude-code (npm) and claude-swap (PyPI) is pinned; their dependencies resolve at build time.
• DEVTEAM_BOX_BIN (tests only) changes where installed looks; a dev process could point it elsewhere on purpose, which changes only what is reported (P6).

One-way doors

None.

🤖 Generated with Claude Code