projectbluefin/lab/hive-contribute

hive-contribute

When to Use

Use when launching, observing, stopping, or changing the lab contributor and its local worker/advisor models or deterministic tooling.

When NOT to Use

Do not start another Hive relay merely to inspect context or test tools. General cluster administration belongs to the relevant cluster operations skill.

Core Process

1. Use the entrypoints below; preserve the separate workstation profile.
2. Exercise changed contracts in a disposable native OMP session first.
3. Follow the verification checks before activating changes at a clean start.

Shape

exo-0 runs the Ornith worker model and ghost runs the Ornith advisor model. Ornith implements; the advisor reviews concurrently per turn via OMP advisor.reviewMode: turn with advisor.syncBacklog: "off". OMP roles are configured by contribute-on: default and smol → ornith on exo-0, advisor → ornith on ghost (or optionally Luna via advisor="luna").

Both pods share one Hive registration: HIVE_SESSION is the pod name, and relays with distinct sessions hold independent tasks under one account (upstream hivecommons/hive v5 contributor-relay.md, "Running multiple backends under one account").

Use

The recipes live in ~/.justfile, so just contribute-on works from any directory. This repo's Justfile has set fallback, which reaches them too. If chezmoi manages that file, merge updates there: downloading a replacement overwrites machine-specific registration defaults. Otherwise install or refresh it:

curl -fsSL https://raw.githubusercontent.com/projectbluefin/lab/main/docs/skills/hive-contribute/contribute.just -o ~/.justfile

just contribute-on       # write Secret, scale models to 1, warm up, scale contributor to 1 and attach
just contribute          # alias of contribute-on
just contribute-attach   # attach to contribute-0 (detach: C-b d)
just contribute-status
just contribute-off      # scale everything to 0; frees both GPUs for video jobs
just contribute-learning-save # save learned skills to the isolated Ghost profile

contribute-on runs a warm-up gate before starting the contributor: it ensures ornith is loaded and responsive on both nodes. Context and safe-tool assets are validated before the registration token is reissued, so an invalid startup bundle does not invalidate the active lease.

The k8s MCP resources_scale tool can toggle the same Deployments and StatefulSet. Scaling up through MCP reuses the last Secret that contribute-on wrote and skips the warm-up.

contribute-on sends, every time, with no login step:

• gh auth token → GH_TOKEN. Hive contributors fork and open PRs as themselves (gh-wrapper.sh).
• The registration file (HIVE_CONTRIBUTE_REGISTRATION; the repo default is ~/.config/hive/contributor.bluefin.env, the owner's chezmoi default is contributor.tunaos-lab.env). Its HIVE_HUB picks the hive, so it decides whose work the lab takes. Its token is reissued with your gh identity on every contribute-on (POST /api/contribute/reissue-token, what upstream's contribute-move does) and written back to the file. That invalidates any other client using this registration. The recipe reissues only the first hub, so keep one hub per file.
• ~/.omp/profiles/ghost/agent/config.yml: isolated Ghost OMP settings, shipped with modelRoles rewritten (yq) to the lab models. The default workstation OMP configuration remains unchanged.
• skills/, managed-skills/ and APPEND_SYSTEM.md from that profile: bundled into the existing Secret, then copied into the container's native OMP agent directory by seed-home. The bundle ships the ponytail skill (profile skills/ponytail symlinks the omp ponytail plugin's skill; tar dereferences it), and APPEND_SYSTEM.md makes it always-on.

Override the paths with HIVE_CONTRIBUTE_REGISTRATION and HIVE_CONTRIBUTE_OMP_CONFIG; KUBECONFIG defaults to ~/.kube/bluespeed.yaml.

Every contribute-on launch reads mcp.json from the contribute-omp ConfigMap and includes it in the existing context bundle. seed-home extracts it into ~/.omp/agent/mcp.json. It enables the Bluefin knowledge server (https://mcp.projectbluefin.io/mcp) and Context7 (https://mcp.context7.com/mcp) over HTTP, independently of workstation or Ghost-profile MCP settings. No workstation API keys are copied. The canonical configuration lives in manifests/contribute.yaml; both local and Luna launches use it. Changing this ConfigMap does not restart the contributor.

The ConfigMap also ships safe-tools.js, checkout.py, and verify.py through the context bundle into ~/.omp/agent/hooks/pre/. New OMP sessions discover the extension there; no workstation profile or contributor pod template is changed. The remaining tooling.md is appended to the profile's APPEND_SYSTEM.md without editing the profile.

• contribute_checkout accepts a Git URL, a new absolute destination, an

optional ref and positive depth (default 1). It fetches that ref into a detached checkout and returns its absolute cwd and commit. Existing destinations are rejected; no fork, push, deletion, retry, or global Git interception occurs. Extra history and fork setup remain explicit Git work.

• Every native bash call must supply an existing absolute cwd; missing,

relative, nonexistent and non-directory values are blocked before execution. Commands are not rewritten and no directory is silently inferred.

• contribute_verify takes cwd, a runner (unittest or junit), and exact

required test IDs. Unittest loads the supplied tests selectors (defaulting to required) with the selected python interpreter. JUnit runs an explicit argv command containing one {report} placeholder and checks its fresh report. Required tests must actually pass; missing, skipped, duplicate JUnit IDs, failed processes or failed reports reject verification. Unrelated skips remain allowed.

• Optional setup is a list of caller-selected argv commands, executed once

in order before testing. Any setup failure stops verification. Use the repository's supported isolated environment and declared dependencies; neither package manager nor packages are guessed or automatically installed.

These helpers are mechanical gates, not a claim that tests cover the task or that the chosen working directory is semantically correct. Native read/edit syntax and complete acceptance-context reads still require model judgment. These are tool-level contracts: arbitrary Git/test commands and Hive completion signals are not intercepted. JUnit evidence comes from the caller's trusted test runner; it is not an attestation against deliberately fabricated reports. New extension modules are not assumed hot-loadable in OMP 18.12.6: install them in the existing startup bundle, verify a disposable native session, and activate on a clean contributor start without abandoning a live task. Source: pinned hook discovery and interception. Use an ESM export default factory for the pinned native loader. Local file:// checkouts use Git's built-in upload-pack command because the slim image may omit its standalone executable.

Rules

• Keep replicas: 1 for llm-d-exo-0 and llm-d-ghost in git, so each

WaitForFirstConsumer PVC binds on first sync (llm-d-advisor-cache is a historical name, kept so ArgoCD does not prune cached models). The contribute StatefulSet stays at 0 in git because its Secret only exists after contribute-on. testing-lab-infra ignores /spec/replicas for all three. That app is applied by hand: kubectl apply -f argocd/infra-application.yaml.

• Don't run the workstation appliance under the same registration while the

lab is on.

• While the routers are up they hold both GPUs, and llm-d-preempt evicts GPU

video jobs. Turn contribution off to hand the GPUs back.

• argo-cluster-read excludes secrets, so Argo workflow pods cannot read the

contribute Secret. Keep it that way.

• Preset INI values cannot start with whitespace (llama.cpp common/preset.cpp

skips ws after =), so Ornith's reasoning-budget message lost its leading space.

• Pinned llama.cpp build: server-vulkan-b11151. Its native MTP path reuses

target weights; enable it with spec-type = draft-mtp and spec-draft-n-max = 1 in the Ornith preset. The cached official Q6_K file contains a draft head (blk.40.*); without MTP the server ignores those tensors. Do not set a separate draft-model path: that loads another model. Verify /slots?model=ornith reports speculative: true and compare the response's timings.predicted_per_second and draft acceptance counters. Source: pinned MTP initialization.

• Benchmark only on an isolated node: disable the advisor with /advisor off,

unload its router model, and run the same binary and cached GGUF on a separate loopback port. Keep context, batching, sampling and prompts identical between configurations. Stop the disposable server and reload the router model before /advisor on. Never benchmark against the busy worker. Code-quality probes need an output allowance above the 3600-token reasoning budget; a shorter allowance can consume every token in reasoning and return no final code.

Choosing the hive

Hives are separate hubs, each with its own registration. hivecommons-hosted hives appear in https://hive.hivecommons.dev/api/saas/my-hives (what hive-contribute hives reads); self-hosted forks do not. tunaOS runs its own spokes, for example reef (wss://reef.tunaos.org/contribute, the tuna-os org; layout in hanthor/dotfiles talos-k8s/hive/README.md).

To join a hub where your GitHub account is already registered (check GET <hub>/api/contribute/me with your gh token as bearer), register will not hand the token back. Reissue it instead: POST <hub>/api/contribute/reissue-token (bearer = gh auth token) returns registration_token and contributor_id. Write them with the hub into a registration file (HIVE_REGISTRATION_TOKEN, HIVE_HUB, CONTRIBUTOR_ID, AGENT_BACKEND=omp, mode 600) and point HIVE_CONTRIBUTE_REGISTRATION at it. hivectl hives add does the same for multi-hub files, but needs podman and only edits ~/.config/hive/contributor.env.

Failure modes