fix(build): use zigbuild for musl supervisor staging

[elezar]

Summary

Use cargo zigbuild for static musl supervisor binary staging whenever it is available, including native CPU architectures. This keeps C dependencies such as aws-lc-sys on the musl target toolchain instead of letting them fall back to the host GNU libc compiler path.

Related Issue

None.

Context

This was reproduced on current origin/main at 27fd31c9 before this change. On the affected machine, the host is aarch64, glibc is 2.42, and cc is a Nix clang wrapper targeting aarch64-unknown-linux-gnu. A native-architecture supervisor build still targets aarch64-unknown-linux-musl, so plain Cargo allowed aws-lc-sys C objects to pick up glibc-only references during a musl link:

• __isoc23_sscanf
• __fprintf_chk

The machine is not too old; the newer glibc/compiler path makes the existing target mismatch visible. The fix is to use the same Zig-backed musl target path for supervisor staging even when the CPU architecture matches the host.

Changes

• Add a shared has_cargo_zigbuild helper to the prebuilt binary staging script.
• Route musl supervisor staging through cargo zigbuild when available, including same-architecture Linux builds.
• Update architecture/build.md with the musl/C-dependency rationale.

Testing

• mise run pre-commit passes
• mise run build:docker:supervisor passes
• mise run build passes
• Unit tests added/updated (not applicable; build script/docs change)
• E2E tests added/updated (not applicable)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated

[elezar]

gator-agent

PR Review Status

Validation: this is maintainer-authored, project-valid build/release work scoped to supervisor binary staging and architecture documentation.
Head SHA: 088f1b9f08888ae53c9519b7d56d643ca7a97683

Review findings:

• No blocking findings remain.
• Nonblocking residual risk: there is no lightweight scripted test for the native supervisor cargo zigbuild selection branch, but the PR reports build smoke coverage.

Docs: architecture documentation was updated; no Fern docs or navigation changes are needed because this does not change direct user-facing UX.

Checks: most required checks are green, but the required gate status re-ran after the gator state update and is currently pending.

Next state: gator:watch-pipeline

[elezar]

gator-agent

Maintainer Approval Needed

Gator validation and PR monitoring are complete.

Validation: maintainer-authored build/release fix scoped to supervisor binary staging and architecture documentation.
Review: no blocking findings remain; residual risk is limited to the lack of a lightweight scripted test for the native supervisor cargo zigbuild branch, with build smoke coverage reported in the PR.
Docs: architecture documentation was updated; Fern docs are not needed because this does not change direct user-facing UX.
Checks: OpenShell / Branch Checks, OpenShell / Helm Lint, DCO, and the required E2E gate statuses are green for head 088f1b9f08888ae53c9519b7d56d643ca7a97683.
E2E: N/A; no test:* label is required for this build-script/docs change.

Human maintainer approval or merge decision is now required.

[elezar]

gator-agent

Re-check After Maintainer Update

I re-evaluated latest head 088f1b9f08888ae53c9519b7d56d643ca7a97683 after TaylorMutch's 2026-06-10 15:16 UTC approval review.

Disposition: resolved; maintainer approval has been received and no blocking gator review or CI items remain.

Remaining items:

• The PR is still open, so a maintainer merge decision remains.

Next state: gator:approval-needed

[github-actions]

Label test:e2e applied for 088f1b9. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[elezar]

gator-agent

Re-check After Pipeline Update

I re-evaluated latest head 088f1b9f08888ae53c9519b7d56d643ca7a97683 after test:e2e was applied and the E2E Label Help workflow requested a rerun of the existing E2E workflow.

Disposition: the prior maintainer-approval handoff is no longer complete because the newly required OpenShell / E2E gate is pending for this head.

Remaining items:

• I reran the existing E2E workflow for 088f1b9; the PR should remain under pipeline watch until the required OpenShell / E2E gate reports green.

Next state: gator:watch-pipeline

[elezar]

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: the PR had been under gator:watch-pipeline after test:e2e was applied; it has since merged, so there is nothing left for gator to monitor.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.