feat(#2693): let the operator pin the claude-code every agent runs

Agents run whatever `claude-code` the meta flake's `nixpkgs` resolves
to, and that is normally a release channel. This one package moves fast
enough that stable trails unstable by weeks — 26.05 is on 2.1.187 while
unstable carries 2.1.220 — and an agent cannot fix it for itself: it
only ever sees the single nixpkgs hive-c0re injects, so an `agent.nix`
has no other tree to reach for.

New host option `services.hyperhive.c0re.claudeCodePackage` takes the
package directly and rides the existing `hyperhiveDocs` threading path —
serveConfigJson -> HiveEnv -> render_flake — to reach each agent as
`hyperhive.claudeCodePath`. Null (the default) is today's behaviour.

What travels is the store *path*, as a plain string literal, not a flake
input: containers share the host's `/nix/store`, so the build is already
reachable inside them with its whole closure and has nothing to travel.
An input would be worse than useless — a `path:/nix/store/<pkg>` input
is re-copied as a reference-less `-source`, which strips exactly the
closure the binary needs.

The catch is that a path written into a generated flake is text, so
nothing in the container's closure keeps the binary alive. The host does
that instead, and gets it for free: the package is interpolated into
`/etc/hyperhive/serve.json`, `builtins.toJSON` preserves string context,
so the /etc entry references it and the system closure gc-roots it for
as long as that generation is the one the agents were rendered from. An
assertion pins that property, because losing the context is invisible at
eval and at deploy — it would surface only as every agent failing to
spawn `claude` whenever the next gc ran.

Container side wraps the path in a symlink farm rather than putting it
on PATH directly: `systemd.services.<name>.path` and
`environment.systemPackages` both coerce a store-path *string* through
`lib.toDerivation`, i.e. `builtins.storePath`, which pure evaluation
rejects. Interpolating the path into a builder is just text and
evaluates anywhere. `claude-code` drops out of systemPackages when a
pin is set, so there is exactly one claude in the container.

Refs #2693

docs/gotchas.md

@@ -84,6 +84,47 @@ scoped, only this one package. This is needed because each per-agent
 operator's host-level `allowUnfree` does **not** propagate in.
 Operators don't need to set anything on their side.
 
+That same isolation is why an agent can't pick a claude out of a
+*different* nixpkgs by itself: a container only ever sees the one
+nixpkgs the meta flake injects, so an `agent.nix` naming the host's
+`nixpkgs-unstable` has nothing to name. A release channel can trail
+unstable by weeks on this package, which is what
+`services.hyperhive.c0re.claudeCodePackage` is for — set it host-side
+and every agent runs that build.
+
+What crosses is the **store path**, not the derivation. Containers
+share the host's `/nix/store`, so the binary is already reachable
+inside them with its whole closure; hive-c0re writes the path into each
+agent's flake as a string literal and the agent module symlinks
+`bin/claude` onto PATH. Two things rule out the obvious alternatives: a
+`path:/nix/store/<pkg>` flake input is re-copied into the store as a
+reference-less `-source` (so the runtime closure never arrives), and
+`lib.types.package` fed a bare path runs `builtins.storePath`, which
+pure evaluation rejects. `hyperhive.docs.source` gets away with being
+an input only because a docs tree has no runtime dependencies.
+
+The `storePath` trap is worth spelling out, because it is not confined
+to options the operator writes: **any** option of type `package` fed a
+store-path *string* coerces through `lib.toDerivation`, i.e.
+`builtins.storePath`. `environment.systemPackages` and
+`systemd.services.<name>.path` both do it (the latter takes plain
+strings like `/run/wrappers` happily, but anything under
+`builtins.storeDir` is treated as a package). So a path handed to the
+container as text has to be wrapped in a real derivation — a symlink
+farm built from the interpolated string — before it can go anywhere a
+package is expected.
+
+The catch is that a path written into a generated flake is text, not a
+reference — the container's closure does not keep the binary alive.
+The **host** does: the package is interpolated into
+`/etc/hyperhive/serve.json`, so it lands in the host's system closure
+and is gc-rooted by the running generation. `builtins.toJSON` preserves
+string context, which is the load-bearing detail; discard the context
+anywhere on that path and `nix-collect-garbage` will eventually take
+the hive's `claude` out from under it. The price of the root is that an
+old `claude-code` can't be reclaimed until every agent has rebuilt past
+it and the old generations are gone.
+
 ## Claude credentials are per-agent
 
 `/var/lib/hyperhive/agents/<name>/claude/` bind-mounts to

docs/turn-loop/claude-invocation.md

@@ -21,6 +21,17 @@ auto-reset / retry decisions in `drive_turn`. The lib returns everything it
 parsed from a turn (usage, cost, context window, resolved model) as
 `Telemetry`, which the policy layer applies to the bus.
 
+**Which `claude` binary.** The bare name `claude`, resolved off the
+harness unit's PATH. By default that's the `claude-code` in the agent's
+own nixpkgs (the meta flake's `nixpkgs` input) via
+`environment.systemPackages`. Since that's usually a release channel and
+this package moves fast, the operator can pin one hive-wide with
+`services.hyperhive.c0re.claudeCodePackage`: its store path is written
+into each agent's flake, and `claude` on PATH becomes a symlink to it
+instead of the container's own `claude-code` — so there's only ever one
+`claude` in the container. Agents pick up a new build on their
+next rebuild, not live. See docs/gotchas.md::`claude-code` is unfree.
+
 Hive-enforced settings ship at `/etc/claude-code/managed-settings.json`
 (claude-code's canonical managed-settings path — precedence #1,
 read-only, un-overridable), wired in `nix/agent-modules/claude-settings.nix`