Overdeck → k3s
audited migration execution
Phase 0 prepared Factory plan blocked Live state unverified

One migration,
two execution tracks.

The attached repository does not contain one continuous K3s implementation. It contains a legacy scheduler compatibility lane and a stricter Factory execution design. The safe process shares the cluster foundation while keeping their workload transports separate.

2
files changed in the attached worktree
0
Factory “preserved WIP” files attached
9
gated phases through final retirement
Audit verdict

Start with evidence, not another install.

Phase 0 lands the useful supplied change safely and gathers current, redacted facts. The first mutating cluster package is generated from that receipt.
Recommended decision

Reconcile the plans before expanding the cluster.

The old scheduler path can be canaried as a temporary adapter. The Factory path must use immutable input, Kubernetes API lifecycle, constrained publication, and no reusable host credential in the coding pod.

01
Land safely

Repair the attached rollback defect and preserve the original unmanaged file.

02
Observe live state

Collect current cluster, node, policy, storage and recovery-door evidence.

03
Mutate in gates

Each later phase is one package, one command, one receipt, one review.

Architecture boundary

Share the foundation. Do not share the risk.

The two tracks may reuse safe policy and lifecycle primitives, but the compatibility transport cannot become the Factory security model.
Compatibility lane

Legacy remote-build scheduler

Incremental migration around existing buildbox/SSH behavior. Feature-gated and suitable only for bounded canaries.

Existing submitter and watcher are present.
Uses host-coupled workspace/credential mechanisms.
Must remain off by default until measured.
Retained only as an explicit transition/fallback lane.
shared safe foundation
Target lane

Factory Kubernetes execution

Restricted, immutable, API-observed execution for coding workloads. This is the long-term architecture.

Digest-pinned image and immutable input ref.
No hostPath, SSH fan-out or node affinity.
Trusted, attempt-bound result publication.
Total cleanup, cancellation and recovery lifecycle.

Cluster foundation

Versioned config, node enrollment, registry, namespaces, RBAC, resources and networking.

Operations

Receipts, observability, backup/restore, upgrades, outage drills and rollback.

Source of truth

Fleet roles plus concrete host identity, committed together after proof.

Attached evidence

What is present, partial, or absent.

Historical markdown claims are treated as documentary evidence until the live collector reproduces them.
Verified in archive
Fleet plane

Declaration, loader, expansion, engine, hardening and CLI are present.

Partial
Legacy K3s

Submitter/watcher exist, focused tests pass, global flag remains off.

Blocked design
Factory K8s

Baseline runner exists; stricter plan records unresolved ship blockers.

Absent
Enrollment

No one-command transactional node enrollment implementation exists.

MODIFIED
modules/workstation/claude/lib/remote-seat-provision.mjs
copy migration logic
MODIFIED
modules/workstation/claude/tests/remote-seat-provision.test.mjs
migration coverage
MISSING
factory-agent-k3s.mjs and related “preserved WIP” files
not in either ZIP
STALE REF
origin/wt/factory-kubernetes-job
5 ahead / 84 behind
Correctness review

Holes converted into phase gates.

Critical

Conflicting workload transports

The older plan relies on host-coupled SSH/hostPath mechanisms that the newer Factory plan explicitly forbids.

Separate tracks
Critical

Reusable host credential in untrusted pod

The Factory plan records a general host GitHub token crossing the coding-container boundary.

Trusted publisher
Critical

Incomplete attempt/ref lifecycle

Cleanup, cancellation, init failure and bounded recovery-retention are not total across every exit path.

State machine
High

Historical receipt treated as current

Host availability and recovery history make a dated plan insufficient proof of today’s cluster.

Live collector
High

Split registration source of truth

Fleet roles and concrete access identity live in separate files; old onboarding instructions target a removed hosts array.

Atomic Git update
High

No accepted backup/restore contract

A single K3s server is not ready for critical cutover without datastore + server-token backup and restore proof.

Phase 1 gate
High

Static join credential risk

A non-expiring agent/server token must not be copied into package files, logs, shell history or candidate storage.

Short-lived token
High

Candidate self-declares trust

Trusted-builder labels must be applied after identity verification by the control plane, not by the joining kubelet.

Protected labels
Medium

Cutover and fallback deletion are conflated

The plan both deletes and depends on the direct SSH path. Those are separate operational decisions.

Two gates
Medium

One command without a transaction ledger

Compressing manual steps is not enough; enrollment needs resumability, proof-before-register and exact rollback.

Durable ledger
Phased execution

Click a phase to inspect its contract.

No phase advances from generated code alone. It advances from returned live evidence and an exact Git result.
Machine onboarding

One trusted-workstation command.

After the OS and Tailscale are ready, the new machine does not need repository, GitHub or cluster-admin credentials.
Target interface

Enroll a named Tailscale machine

bash tools/k3s/enroll-node.sh debian4
Responsibility boundary

Nearly all deterministic work is packaged.

AAssistant package

  • Audit plans, branches and implementation.
  • Write code, tests, manifests, policies and rollback.
  • Build changed-files ZIP and one application script.
  • Create worktree, branch, commit, push and PR automation.
  • Analyze returned receipt and produce the next phase.

OOwner / physical boundary

  • Install base OS and Tailscale; admit the device.
  • Approve root, tailnet, registry and GitHub App policy.
  • Run one supplied command on the trusted workstation.
  • Keep console/physical recovery available for reboot/storage work.
  • Approve protected-main merges and return the receipt.
Delivery loop

ZIP → command → evidence → next phase.

The loop keeps execution local to the owner’s trusted system while moving design, implementation and analysis into repeatable packages.
1 · Auditread plans + prior receipt
2 · Buildcode, tests, rollback
3 · PackageZIP + one script
4 · Executetrusted workstation
5 · Proveredacted receipt
6 · Landbranch / PR / main

A failed gate does not produce the next mutating phase. It produces a correction package or explicit rollback based on captured evidence.

Executable now

Phase 0: safe landing + read-only receipt.

This phase changes repository code in a new worktree branch. It does not install K3s, restart services, harden hosts or mutate Kubernetes.
No live cluster mutation

Run from the trusted workstation

bash apply-overdeck-k3s-phase0.sh /home/user/Projects/overdeck
Verifies package checksums and base compatibility.
Creates an isolated worktree from current origin/main.
Applies the rollback repair, audit docs and collector.
Runs focused gates before committing.
Collects live state without reading Secret/token values.
Pushes a branch and opens a PR when authentication is available.
Produces one result archive to return for Phase 1.
Non-zero discovery probes are evidence, not automatic defects. An unreachable node or absent command is recorded for analysis instead of aborting the receipt.

Verification already performed

GateAudit result
Remote seat focused suitePass
Rollback failure injectionPass
Legacy K3s unit suitePass
Factory K8s focused tests6 passed
Fleet focused suitesPass as non-root
Live K3s integrationSkipped: no audit kubeconfig
Collector offline testPass

The owner-side script repeats deterministic gates in the real checkout and records environmental skips rather than manufacturing a green result.