nix: add dev-shell prefetch script for cloud setup phase

Add build-tools/nix/prefetch-devshell.sh, which realises the `nix develop`
shell into /nix/store, plus README-prefetch.md documenting how to wire it into
a Claude Code (web) environment setup script.

Running the prefetch in the setup-script phase (whose filesystem output is
snapshotted and reused) moves the slow first `nix develop` off the interactive
session: later sessions find every store path already present and fetch
nothing. The script is idempotent, pins a gc-root outside the working tree,
and no-ops cleanly when nix is absent.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1ArmS9aNbCxuwhC7zYLBx

Author: claude

build-tools/nix/README-prefetch.md

@@ -0,0 +1,59 @@
+# Prefetching the Nix dev shell (Claude Code on the web)
+
+`build-tools/nix/prefetch-devshell.sh` realises this project's `nix develop`
+shell into the local `/nix/store`. Its purpose is to move the (potentially
+slow) first `nix develop` out of the interactive session and into the cloud
+environment's **setup-script** phase, whose filesystem output is cached and
+reused by every later session.
+
+This complements the `git+https` flake inputs (see the note at the top of
+`flake.nix`): the flake change makes resolution *possible* behind the sandbox
+proxy; the prefetch makes it *instant* for subsequent sessions.
+
+## Where to put it / how to run it
+
+The script itself lives in the repo (version-controlled and reviewable). You
+wire it into the environment via the Claude Code web UI:
+
+1. Open the environment selector (cloud icon) → your environment → **Edit**.
+2. In the **Setup script** field, add:
+
+   ```bash
+   ./build-tools/nix/prefetch-devshell.sh
+   ```
+
+   (Keep any existing setup-script lines; just append this one.)
+3. Ensure **Network access** is **Trusted** (or a **Custom** list that keeps
+   the defaults plus `cache.nixos.org`, `cache.iog.io`, and `github.com`).
+   `None` will make the prefetch fail.
+4. Save. The next *new* session rebuilds the environment cache and runs the
+   prefetch once.
+
+## When it runs
+
+| Trigger | Prefetch runs? |
+|---|---|
+| First session in the environment | Yes (populates the cache) |
+| Later *new* sessions | No — served from the cached snapshot |
+| **Resuming** an existing session | No |
+| You change the setup script or the allowed-hosts list | Yes (cache rebuilds) |
+| Cache expiry (~7 days) | Yes (cache rebuilds) |
+
+Reference: <https://code.claude.com/docs/en/claude-code-on-the-web> (Setup
+scripts, Environment caching, Network access).
+
+## Notes
+
+- **Idempotent.** Once the store is warm the script finishes in seconds, so
+  it is harmless to run repeatedly or by hand on any machine with Nix.
+- **gc-root.** It pins the realised shell via a `nix develop --profile`
+  gc-root at `$HOME/.cache/fls/devshell-profile` (override with
+  `FLS_DEVSHELL_GCROOT`) so the paths are not garbage-collected before the
+  session starts. The path is outside the working tree, so `git status` stays
+  clean.
+- **Setup script vs. SessionStart hook.** This is deliberately a *setup
+  script*, not a `.claude` SessionStart hook: only the setup-script phase is
+  cached. A SessionStart hook would re-realise the shell on every session
+  start/resume and add latency for no caching benefit.
+- **No `nix`?** The script exits 0 with a message, so it is safe in
+  environments where Nix is not installed.

build-tools/nix/prefetch-devshell.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+#
+# Prefetch the Nix dev shell into the local /nix/store.
+#
+# Intended to run as a Claude Code (web) *setup script* — see
+# build-tools/nix/README-prefetch.md. Setup-script output is snapshotted and
+# reused by later sessions, so realising the dev shell here means subsequent
+# `nix develop` invocations find every path already on disk and perform no
+# network fetches at all.
+#
+# It is also safe to run by hand on any machine: it only populates the store
+# and a gc-root, and re-runs are fast once the store is warm.
+set -euo pipefail
+
+# Resolve the repo root from this script's location so the setup script can
+# invoke it from anywhere.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$REPO_ROOT"
+
+export NIX_CONFIG="experimental-features = nix-command flakes"
+
+if ! command -v nix >/dev/null 2>&1; then
+  echo "prefetch-devshell: 'nix' not found on PATH; nothing to do." >&2
+  exit 0
+fi
+
+# Keep a gc-root outside the working tree so the realised paths survive a
+# garbage collection between setup and the interactive session, and so the
+# git tree stays clean.
+GCROOT_DIR="${FLS_DEVSHELL_GCROOT:-$HOME/.cache/fls/devshell-profile}"
+mkdir -p "$(dirname "$GCROOT_DIR")"
+
+echo "prefetch-devshell: realising dev shell into the store (gc-root: $GCROOT_DIR)"
+
+# `--profile` doubles as a persistent gc-root. `--command true` builds the
+# shell environment and exits without dropping into an interactive shell.
+nix develop --profile "$GCROOT_DIR" --command true
+
+echo "prefetch-devshell: done. Verifying Agda is available:"
+nix develop --profile "$GCROOT_DIR" --command agda --version