Put the Route A driver in the repo and turn staging on for its release

[MaxGhenis]

Summary

Until now the Route A driver lived only on the build machine, and its release passed --no-staging. Pavel asked for both to change (2026-10-05). This PR:

• moves the driver into tools/route_a/;
• turns staging telemetry on for its release stage, so the next Route A attempt shows up on the dashboard's Build progress tab.

What moved (tools/route_a/):

• route_a.sh: the driver. Every machine path now comes from a settings file. The settings file is route_a.env, which is git-ignored, or the file ROUTE_A_ENV names; route_a.env.example is committed.
• supervise.py: copied unchanged. It does admission, the RSS, wall and CPU limits, and the DISK_FLOOR kill, and writes RESULT.json. The driver writes ACCEPTED once it accepts a result.
• sample_series.py: the resource sampler. It's unchanged apart from datetime.UTC, for lint.
• check_flags.py: replaces the driver's grep-for-a-quoted-flag check. It checks the release flags against the release parser's literal add_argument declarations without importing the tool, and those flags now include any in RELEASE_EXTRA_ARGS.
• with_hf_token.sh: fetches the HF token at exec time (below).
• README.md: configuration, the stages and their gates, the published run's exact release argv, the Modal-base hand-off, and what the Build progress tab shows.

What changed: staging.

• With ROUTE_A_STAGING=1 (the default), the release runs under with_hf_token.sh <agent-secret> <release argv>. The wrapper:

  • turns off shell tracing and unsets every inherited HF token variable;
  • calls agent-secret get HUGGING_FACE_TOKEN_MAX, refusing if the lookup fails or returns an empty value;
  • exports HF_TOKEN, then execs the release.

  The driver writes release-config.json before the supervisor launches anything, so the config records only the wrapper and helper paths.

• ROUTE_A_STAGING=0 restores --no-staging, strips the HF variables and never calls the helper.

• Any other value of ROUTE_A_STAGING is refused, and so is --no-staging inside RELEASE_EXTRA_ARGS.

• The base, prefetch, both gate preflights and the publisher preflight behave as before; the preflights still strip secrets and run with the Hub offline.

Unchanged:

• every gate and refusal: input digests and sizes, the commit and main-ancestry checks, the feed, ASEC, crosswalk and SPM pins, admission, the disk floor, both release-gate preflights, the publisher's --preflight-only, and the published: false hand-off;
• there is still no publish stage;
• the block ladder default stays on d713's CT-fixed file (6840b990…, 18,991,218 bytes);
• the published 4b57d15a2 release and its run directory are untouched.

Invariants (tested)

• Declared flags. Every flag the driver passes to the release is declared by tools/build_us_fiscal_refresh_release.py's parser, with staging on and off and with the example's extra arguments.
• The staging switch. --no-staging is in the release argv if and only if ROUTE_A_STAGING=0. The wrapper is the launcher if and only if ROUTE_A_STAGING=1.
• The token reaches only the child. A dummy credential reaches the release child's environment, and never its argv, the stage config, the supervisor's logs or any file, including under set -x and through the helper's stderr.
• Bad lookups are refused. If the lookup fails or returns an empty value, the wrapper exits non-zero without running the release.
• Refusals still hold. RELEASE_EXTRA_ARGS refusals still fire, including the --flag=value forms the old matcher missed.
• Clean sources. No file under tools/route_a/ contains a /Users/ path or a token-shaped string.
• Shell checks. Both scripts pass bash -n and shellcheck.

Tests

• pytest packages/microcosm-build/tests/engine_free/us/test_route_a_driver.py packages/microcosm-build/tests/engine_workflow/us/test_route_a_supervisor_secrets.py: 25 passed, run locally against this branch's sources. Dropping exec from the wrapper, or echoing the token, fails both secret tests.
• ruff check and ruff format --check pass on the new files, and shellcheck passes.
• tools/ci_test_plan.py verify passes; the module is in the engine-free US group.
• Mutation audit on throwaway copies: 41 of 41 mutations were caught. They covered each test's guard, for example dropping exec, leaking the token through argv or set -x, accepting an empty lookup, adding an undeclared flag, and flipping each staging mode.
• No build, release, real token lookup or upload was run.

Judgment calls

• Example defaults. The example keeps the published run's operator settings: the d122 dense national/state surface, batch size 2000, the export-mass reference and the d490 tail register. It grants no new waiver. Under d490 a re-measured register with the same threshold and the same or fewer columns may be applied; a new column still needs a ruling.
• Run root. The example's RUN_ROOT is a fresh directory, because an existing base-sup/ACCEPTED skips the base stage. Pointing LADDER at the CT ladder alone would not rebuild an accepted base.
• --resolve. It keeps its old exit behavior: commit blockers are logged but don't on their own make it exit non-zero.
• Modal files. These are unchanged. The README says the committed plan and local reference target the old ladder, so a CT-ladder base needs its own plan and comparison evidence.
• Platform. This stays a macOS bash operator tool (stat -f).
• Where the secret test runs. The supervisor imports psutil, which the engine-free job doesn't install. Adding it to the dev group would move uv.lock, which the Primary-QRF worker identity pins (APPROVED_UV_LOCK_SHA256), so the test is split instead and uv.lock is untouched. The engine-free test runs the wrapper directly under bash -x and reads the child's argv with ps. engine_workflow/us/test_route_a_supervisor_secrets.py runs the same check through the real supervisor in the US engine job, which has psutil through the US extra.

Requested by Pavel Makarchuk. Related: microcosm#1082, which keeps staging on for every build; reviewed separately.

🤖 Generated with Claude Code