FAQ: A Free Shell Run Is Not a Toolchain Pin

I keep seeing the same shortcut in merge threads.
Someone pastes a model-written install script and calls it done.
Did that free server prove a pin, or only a lucky minute?

The claim in the thread

The story sounds tidy, and tidy stories skip evidence.
Free model access wrote the commands in one pass.
A free server ran them, so the toolchain is called portable.

I do not buy that chain, and you should not either.
A draft is text, and a warm shell is a moment.
Where is the digest that a stranger can rerun tomorrow?

Where those free options fit

I use MonkeyCode only as the scratch pad in this flow.
Disclosure: This article was prepared as part of MonkeyCode's product outreach.
Free model access can draft a script you still must pin.

A free server option can give you one shell for a dry run.
It does not name your image, your lockfile, or your digest.
I still capture those three things in the repo I control.

Myth: fluent text means current docs

People treat a smooth answer as a dated snapshot.
It is not a snapshot, and it has no freeze date.
Ask which commit that answer actually claims it read.

I paste the suggested commands into a file before I run them.
I do not execute that file on any host yet.
Would you merge a patch you have not even hashed?

install -d .toolchain
cp /tmp/suggested.sh .toolchain/suggested.sh
sha256sum .toolchain/suggested.sh | tee .toolchain/suggested.sha256
git diff -- .toolchain/suggested.sh

That hash only names the text you saved.
It does not bless the commands sitting inside it.
If the diff is noisy, stop and read before you run.

Myth: one warm shell is every later shell

A warm shell remembers packages you installed earlier today.
Your CI job often starts from a clean declared image.
Those are different machines with different package indexes.

Why would today's index match next week's clean job?
I record the shell before I install anything new.
A missing line in that record is a missing fact.

{
  date -u +%Y-%m-%dT%H:%M:%SZ
  uname -a
  id
  command -v git || true
  git --version || true
  command -v python3 || true
  python3 --version || true
} | tee .toolchain/shell-before.txt

Read shell-before.txt before you celebrate a green prompt.
If python3 was already there, your script did not install it.
If the user is root, your laptop user may not match.

Myth: a passing compile means an honest lock

The build passed, so the dependencies must be pinned.
A passing compile can still float on today's index.
Tomorrow the same command can fetch a different tarball.

I want three files present, not a cheerful prompt.
If the lockfile test fails, stop and add a real lock.
Do not invent a pin inside the chat window.

test -f package-lock.json || test -f poetry.lock || test -f go.sum
test -f .toolchain/suggested.sha256
test -f .toolchain/shell-before.txt

That trio is a gate for the story, not a security audit.
A present lockfile can still be stale or partial.
Open it and see whether the tool you ran is even listed.

Myth: the host remembered your proof

People assume the free host keeps the transcript for them.
I would not bet a later rebuild on that memory.
Free access can change, and I will not invent a quota.

Copy the evidence into git, or into a job artifact you own.
Leave the remote shell as a scratch pad only.
Did you push the pin, or only admire it locally?

sha256sum .toolchain/shell-before.txt | tee .toolchain/shell-before.sha256
git add .toolchain/suggested.sha256 .toolchain/shell-before.txt .toolchain/shell-before.sha256
git status --short -- .toolchain

git status here is only a local index check.
It is not a remote pipeline result, and it never was.
Push the pin if you want another machine to see it.

Myth: a version string is a digest

python3 --version is a label, not a content hash.
Two hosts can print the same label and differ underneath.
I want the lockfile hash, not a slogan from --version.

When the tool publishes a tarball, hash that tarball too.
Store the hash beside the suggested script in .toolchain.
If you cannot hash it, you cannot claim you pinned it.

# shape only; operator sets TOOL_URL from a doc opened today
curl -fsSL -o .toolchain/tool.tgz "$TOOL_URL"
sha256sum .toolchain/tool.tgz | tee .toolchain/tool.sha256

I mark that snippet as a shape, not a vendor pin.
I do not ship a sample URL, because sample URLs rot.
You fill TOOL_URL from a primary doc you opened today.

A check you can rerun

This script is a proposal, not a benchmark I measured.
It fails closed when a pin file is missing or edited.
Run it on your machine before you trust any free shell.

#!/usr/bin/env bash
set -euo pipefail

need=(
  .toolchain/suggested.sha256
  .toolchain/shell-before.txt
  .toolchain/shell-before.sha256
)

for f in "${need[@]}"; do
  if [[ ! -s "$f" ]]; then
    printf 'missing pin file: %s\n' "$f" >&2
    exit 2
  fi
done

if ! sha256sum -c .toolchain/shell-before.sha256; then
  printf 'shell snapshot hash mismatch\n' >&2
  exit 3
fi

if [[ ! -f package-lock.json && ! -f poetry.lock && ! -f go.sum ]]; then
  printf 'no lockfile in repo root\n' >&2
  exit 4
fi

printf 'toolchain pin files present\n'

What the exits mean

Save it as scripts/check-toolchain-pin.sh and run it from the repo root.
Exit 2 means you skipped a snapshot file.
Exit 3 means the snapshot changed after you hashed it.

Exit 4 means the repo still has no lockfile.
Exit 0 only means those files exist and the hash matches.
It does not mean the build is safe to ship.

bash scripts/check-toolchain-pin.sh
printf 'exit=%s\n' "$?"

How I walk the dry run

I use four steps, and I do not skip ahead.
Each step answers one question with a file.
If a step cannot write a file, the myth stays a myth.

1. Save the model text and hash it before any install.
2. Record uname, id, and tool paths in shell-before.txt.
3. Add or confirm a lockfile, then hash the fetched tarball.
4. Run the check script, then commit the .toolchain files.

Step one stops blind execution of fluent text.
Step two stops the claim that this shell matches CI.
Steps three and four stop the floating index story.

Decision table

I keep this table next to the script during review.
It maps a repeated claim to the evidence I require.
No evidence means the corrected label, not the myth.

Claim I hear	Evidence I require	Corrected label
The model checked current docs	A commit or doc URL plus the date I opened it	Untrusted draft text
The free shell matches CI	Image name, digest, and a clean-job rerun	One warm shell only
The lockfile is honest	Lockfile in git, plus a fresh install test	Still floating
The host stored our proof	Files committed or uploaded as artifacts	Scratch pad memory
Free access will stay available	A written limit you can cite today	An option, not a promise
A version string is a pin	Content hash of the tarball you fetched	A label, not a digest

Who should skip this

This flow will not sign a release or audit a registry.
Hashing your notes does not prove the tarball is clean.
Skip it when you need a signed, reviewed release path.

Skip it if you cannot read the shell you are running.
A script you do not understand is another borrowed myth.
Also skip it when secrets already sit in that free shell.

Do not paste tokens into a shared or free host.
Record versions and hashes, never credentials or cookies.
A pin file should be boring enough to commit.

The script only looks for three lockfile names in the repo root.
Cargo, Bundler, and other ecosystems need their own names added.
Treat the list as a starter, not a complete matrix.

The hash check assumes you run it from the repo root.
sha256sum -c trusts the paths written in the hash file.
Move the repo, and you must regenerate those hash lines.

The model I keep instead

A free model can draft commands faster than I type them.
A free server can let me try those commands a single time.
I still pin inside a repo I control, on an image I name.

Three questions close every review I am willing to join.
Where is the digest, and where is the lockfile?
Which clean image reran the same command after the chat?

If any answer is "the chat," I stop the review there.
Fluency is not a pin, and a warm shell is not frozen.
Call it a dry run until the files exist in git.

If you need a scratch shell, use it only for that first dry run.
Then put the pin in the repo you already review.