GPU-Server Private Boundary

This is the source of truth for the recurring GPU-server public/private boundary.

Just want to reach the channel? See private-comms-channel.md — the public stub that points to the live private control bridge in fak-private. This doc explains what is public vs private and why; that stub is the entry point.

Operating the box fleet? See fleet.md — the public, transport-agnostic Go core (fleetctl: roster + fold + readiness score + render). It folds the per-box report JSON the private bridge writes; the boundary below is the rule it lives inside.

Public tree

The public fak tree may keep scrubbed benchmark evidence, runbooks, and result summaries for the GPU-server work. Those artifacts must use generic public language (GPU server, hardware class, no lab host/IP/path/token) and must pass the scrub and file-admission gates.

Examples that can be public:

• docs/benchmarks/*GPU-SERVER*.md
• scrubbed result artifacts under experiments/qwen36/...
• GPU acceptance scripts that run local commands and do not implement the lab control channel
• scrubbed lab-machine readiness records using the fak.lab_readiness/v1 status vocabulary from fleet.md

Private tree

The live control plane for the lab GPU server is private operational plumbing. It belongs in fak-private, not here.

Private-only paths and concepts:

• private bridge commands and support packages
• private notification cleanup helpers
• private bridge/control packages
• sunset private Python bridge paths
• GPU-server machine catalog runs under private machine IDs
• raw control-plane state, transcripts, tokens, workspace IDs, lab hostnames, and operator paths

Readiness handoff

The public tree may say whether a lab machine class is usable for dev work, but only as a scrubbed status class. Private bridge output is folded on the private side into one of:

• READY_FOR_DEV_WORK
• WAIT_PRIVATE_RECOVERY
• GATEWAY_UNREACHABLE
• AUTH_OR_CHANNEL_BLOCKED
• INDETERMINATE

That folded status is public evidence; the raw private command output is not. If a status cannot be produced without carrying a host, endpoint, channel id, token, account id, raw transcript, or private path, publish INDETERMINATE and keep the raw evidence private. Dispatch and super-loop code must fail closed on every status except READY_FOR_DEV_WORK.

Confirming a feeder actually posted

The feeders fail OPEN by design (a secret-less run renders to the step summary and exits 0), so a misconfigured feeder is silent. fak slack health is the public watchdog that CONFIRMS a post landed: per surface it folds resolution + auth.test + a real conversations.history read into an OK | INCOMPLETE | AUTH_FAIL | STALE verdict and exits non-zero on any non-OK. The unattended arm is .github/workflows/slack-watchdog.yml, which files one deduped issue on a non-OK verdict. Like every public Slack surface here, it carries no token, channel id, or lab identifier — it reads them from env/vars at run time. See cli-reference.md.

Go vs Python

New public tooling is Go. Add a fak subcommand or a small cmd/<name>/ binary, with pure logic under internal/<name>/ where appropriate. Do not add a new tools/*.py.

The public, transport-agnostic fleet core now exists in Go: cmd/fleetctl/ (fleetctl) is the Go home the scattered tools/fleet_*.py helpers port into — a typed roster, a deterministic fold + readiness score, and a render that stays readable at 100+ boxes. It reads the per-box report JSON the private bridge writes (the seam is a data contract, not a code import), so the live control plane stays private while the core stays public. See fleet.md.

Existing Python tools are grandfathered only. The allowlist in internal/pythongate can shrink when a Python tool is ported or sunset, but it must not grow. Restoring the removed private bridge Python tool would violate both rules: it is a new Python path after deletion and it is private GPU-server control-plane code.

Enforced by

• internal/pythongate: refuses new tracked tools/*.py
• tools/check_committed_files.py: refuses private-only GPU-server control paths
• .gitignore: keeps private GPU-server run outputs and bridge working copies out of status
• tools/scrub_public_copy.py: strips private GPU-server machine runs and lab identifiers from exported copies

  Private run directories: opaque and outside this checkout

Control-plane prompts, stdout/stderr, worker manifests, bridge transcripts, and raw benchmark artifacts are private even when their contents appear harmless. Do not create machine-named or campaign-named directories in the public checkout (for example, .codex-<machine>-runs). Resolve an opaque destination first:

$RunDir = fak lab private-path --create

The default is <paired-private-repo>/fleet-runs/codex/<UTC>-<random>, with the private root resolved from FAK_PRIVATE_ROOT or the sibling ../fak-private checkout. The command deliberately accepts no hardware, channel, customer, model, or campaign label, so private identifiers do not leak through directory names or process arguments. It fails closed when the paired private root is unavailable or points inside the public checkout. Only separately scrubbed, reproducible summaries belong in this repository.