feat(agent-os): run Firstmate as a portable Kubernetes agent

[robinbraemer]

What Changed

• Package Firstmate as a portable Kubernetes Agent OS with a persistent container toolchain, isolated recoverable crewmate Pods, an Akua-rendered package, and an OrbStack development profile.
• Add immutable source and image provenance plus guarded publication and Kubernetes lifecycle operations with installation ownership, freshness checks, conditional mutations, rollback validation, and safe deletion.
• Synchronize Firstmate runtime improvements across Pi supervision, Zellij recovery, backend dispatch, secondmate routing markers, bootstrap diagnostics, and X-mode follow-up context.

Risk Assessment

✅ Low: Captain, the previously identified publication and Kubernetes ownership races are closed with bounded, fail-closed mechanics, and this pass found no remaining material issue.

Testing

Completed 1 recorded test check.

Pipeline

Updates from git push no-mistakes

⏭️ **intent** - skipped

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

🔧 **Review** - 7 issues found → auto-fixed (3) ✅

• 🚨 bin/fm-bootstrap.sh:351 - Adding akua to COMMON_TOOLS makes it a universal bootstrap dependency, although the documentation defines Akua as optional and only the Kubernetes tooling consumes it. Move this check into the Kubernetes-specific workflow so ordinary Firstmate sessions do not report MISSING and block dispatch.
• 🚨 bin/agent-os-crewmate.sh:57 - purge --yes deletes the computed Pod and PVC names without verifying that those objects belong to this crewmate. In a shared namespace, a name collision can destroy unrelated persistent data; validate immutable ownership markers before both create/adoption and deletion, and fail closed.
• ⚠️ tools/agent-os/packages/firstmate/package.k:34 - Installation applies the Agent OS ownership label to an existing namespace, effectively adopting it. The later namespace-deletion guard trusts only that label, so delete-namespace --yes can delete unrelated resources from a pre-existing shared namespace; refuse adoption by default or use a stronger ownership token.
• 🚨 tools/agent-os/skills-lock.json:5 - The distributed Effect skill bundle records only a repository name and content hash, while the source-provenance and third-party records contain no immutable upstream revision, license, or notice for it. Record the exact source revision and redistribution terms, or remove the vendored bundle before publication.
• ⚠️ .github/workflows/agent-os-image.yml:151 - The publishing job gives GITHUB_TOKEN package-write authority to actions referenced by mutable major-version tags. Pin login, build/push, checkout, and the other third-party actions to full commit SHAs to prevent tag retargeting from becoming a release supply-chain compromise.
• ⚠️ bin/fm-x-link.sh:141 - The link command always permits relay lookup while resolving reply context, including in dry-run mode. If local state is incomplete and credentials exist, a supposedly local preview sends request metadata to the relay; pass allow_relay=0 whenever dry-run is enabled.
• ⚠️ .github/workflows/agent-os-image.yml:101 - Every non-PR push, including arbitrary tag pushes, can publish an image after only the provenance test; the job has no dependency on the repository's behavioral CI. Require the full CI result before publication, or explicitly restrict tags to already-tested main commits.

🔧 Fix: Harden Agent OS ownership, provenance, and publication
4 issues (2 errors, 2 warnings) still open:

• 🚨 .github/workflows/agent-os-image.yml:101 - Successful CI runs can finish out of order, and this gate does not verify that head_sha is still the current protected-main commit. An older run can therefore publish after a newer one and overwrite latest; reject stale workflow runs immediately before publication or otherwise enforce monotonic releases. GitHub documents that concurrency ordering is not guaranteed.
• 🚨 bin/agent-os-kubernetes.sh:64 - The ownership checks read each object's UID but discard it before later apply or name-only deletion; the crewmate helper repeats the same pattern. A resource created or replaced between verification and mutation can consequently be adopted or deleted, including a foreign PVC. Use atomic create/resource-version updates and UID-preconditioned deletes, skipping deletion when the verified object was absent. Kubernetes provides UID and resourceVersion deletion preconditions.
• ⚠️ bin/agent-os-kubernetes.sh:163 - rollback mutates the named StatefulSet without checking its installation UUID, so a wrong namespace can roll back an unrelated workload despite the new ownership boundary. Verify the namespace and StatefulSet ownership before rollout undo.
• ⚠️ tools/agent-os/packages/firstmate/inputs.example.yaml:2 - The operational helper defaults to this example file, which contains a fixed, publicly reused installation UUID. An install that omits AGENT_OS_INPUTS can treat another default-config namespace as its own; require an explicit input file, generate and persist a fresh UUID, or reject this example UUID for non-local installs.

🔧 Fix: Harden Kubernetes ownership and publication freshness
3 issues (1 error, 2 warnings) still open:

• 🚨 .github/workflows/agent-os-image.yml:176 - The freshness check runs before a potentially long multi-architecture build, so main can advance before the action pushes latest; no replacement workflow exists to cancel this run until the newer commit's CI finishes. Build without publishing, refresh main again immediately before the registry mutation, then publish the verified digest/tag. GitHub does not guarantee concurrency ordering.
• ⚠️ bin/agent-os-kubernetes.sh:202 - rollback unconditionally requires Agent OS ownership labels on the namespace, but supported createNamespace: false installations deliberately neither create nor label that shared namespace. Rollback therefore always fails for this package mode; verify namespace ownership conditionally, or persist and compare its UID without adopting it.
• ⚠️ bin/agent-os-kubernetes-cas.sh:87 - Raw conditional deletes return as soon as the API accepts the DELETE and bypass kubectl delete's waiter. Purge, uninstall, and namespace deletion can report completion while Pods or PVC finalizers remain, causing immediate recreation or reinstall to fail; wait until the captured UID disappears, treating a replacement UID as completion. The kubectl raw-delete path returns directly after the request.

🔧 Fix: Close publication, rollback, and delete races
✅ Re-checked - no issues remain.

✅ **Test** - passed

✅ No issues found.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"

✅ **Document** - passed

✅ No issues found.

🔧 **Lint** - 1 issue found → auto-fixed ✅

• ⚠️ linter found issues (exit code 1)

🔧 Fix: Captain: suppress literal-only ShellCheck warnings
✅ Re-checked - no issues remain.

✅ **Push** - passed

✅ No issues found.